Attributes with GAS

The GAS adapter (module PulseFoundationGAS) lets every Pulse plugin read and change the attributes of an ability system component (ASC) through the same contract as the Pulse Attributes component: IPulseAttributeSource. Conditions, costs, HUDs, AI and quests ask Pulse.Stat.Health and never need to know that the number lives in an attribute set. Use it when your game already has GAS; without GAS the Pulse Attributes component is simpler.

What the adapter adds on top of GAS: Pulse changes and modifiers as gameplay effects, the Pulse events and messages (Changed, Depleted, Restored, RangeChanged) for every change, also those of your own effects, and Pulse rules (rates, bands, pause tags and the max change rule) without a tick.

Setup

  1. Enable Pulse Foundation. Its .uplugin turns on the engine plugin GameplayAbilities; the module PulseFoundationGAS loads with it. Game modules that use the C++ API add PulseFoundationGAS to their Build.cs.
  2. Put the component Pulse GAS Attributes (UPulseGASAttributeComponent, PulseGASAttributeComponent.h) on the actor that owns the ASC: the pawn or the player state. The Set Up step of Foundation in the Pulse window does it for the player state (it turns on the automatic component GAS Attribute Component of Project Settings > Pulse > Foundation GAS) or for the player pawn.
  3. Tell Pulse which attribute set holds which Pulse attribute: an attribute map.
  4. Call Pulse::Attributes::GAS::NotifyAbilitySystemReady after InitAbilityActorInfo:
void AMyCharacter::PossessedBy(AController* NewController)
{
	Super::PossessedBy(NewController);

	AbilitySystem->InitAbilityActorInfo(this, this);
	Pulse::Attributes::GAS::NotifyAbilitySystemReady(this);
}

With the ASC on the player state, clients init it when the player state arrives:

void AMyCharacter::OnRep_PlayerState()
{
	Super::OnRep_PlayerState();

	if (AMyPlayerState* state = GetPlayerState<AMyPlayerState>())
	{
		state->AbilitySystem->InitAbilityActorInfo(state, this);
		Pulse::Attributes::GAS::NotifyAbilitySystemReady(state);
	}
}

In Blueprint the node is Notify Ability System Ready (category Pulse > Foundation > GAS). The component also binds in BeginPlay, when the controller possesses another pawn and when its player state gets another pawn (also for other players on clients, who have no controller there), so an ASC that is ready before BeginPlay needs no call. Binding again on the server (another ASC, or attribute sets granted after binding) keeps the own attributes and the saved modifiers: they move to the new binding like a load (CatchUp Load). Bound again to the same ASC it also keeps the unsaved modifiers of other systems (equipment, tuning; the bands give theirs again). A binding after BeginPlay (an ASC that arrived late, or another one) sends SourceReady again, so listeners read the source again and give lost modifiers again. Without an ASC, Read answers unknown, Change answers Pulse.Result.Failure.Attribute.Unknown, and the log names the actor and the fix.

Adding the component automatically. NotifyAbilitySystemReady adds the component on the server when the owner has none, no other attribute source answers for it (its own, or the pawn of a player state) and Add Component When Ready (Project Settings > Pulse > Foundation GAS, on by default) is on. So enemies, dummies and anything else with an ASC answer Pulse without work in each Blueprint. Turn it off to decide per actor; the Check of Foundation then reports Blueprints that have an ASC but no Pulse GAS Attributes component. A component added at run time replicates as a dynamic component.

UPulseGASAttributeComponent::FindGASAttributeComponent (Blueprint Find Pulse GAS Attributes Component) finds the component of any actor of a player the way Pulse::Attributes::FindSource finds a source.

Mapping

A Pulse GAS Attribute Map (UPulseGASAttributeMap, Create step of Foundation) lists one entry per Pulse attribute:

Field What it is
Attribute The Pulse attribute (Pulse.Stat.Health).
Gameplay Attribute The attribute of an attribute set that holds it (UMyHealthSet.Health).
Kind Pool (a value between Min and Max that changes in the game) or Stat (a base value with modifiers).
Max Attribute The Pulse attribute of another entry that is the upper bound (Health up to MaxHealth); empty for the fixed Max Value.
Min Value, Max Value The fixed bounds; a Max Value that is not above Min Value (0 by default) means no upper bound, so a stat from 1 needs no Max Value.
Modifier Effect The effect that carries Pulse modifiers on this attribute (modifier effects); empty refuses them.

A component uses its own Map, else Default Map of Project Settings > Pulse > Foundation GAS, then the mappings that plugins register in code; an entry of a map wins over a registered one with the same tag. Between registrations the first one registered wins (a warning names both owners): a game that registers its own mapping for a tag that a plugin maps already (Health, Shield and Stamina of PulseAttributes) loses, so it puts that entry into a map asset instead. A plugin with its own sets registers them in StartupModule and removes them in ShutdownModule:

Pulse::Attributes::GAS::RegisterMappings(TEXT("MyPlugin"), { HealthMapping, MaxHealthMapping });
Pulse::Attributes::GAS::UnregisterMappings(TEXT("MyPlugin"));

IsDataValid and Validate of the map (and Pulse::Attributes::GAS::ValidateMappings for code) report a tag twice, a gameplay attribute without a set or mapped twice (the first entry counts), a Max Attribute that is no entry and a modifier effect that does not fit.

Clamping. Pulse clamps when it reads (Value between Min and Max, Base as stored) and when it changes; your attribute set only needs to clamp down (health not below 0). Do not pull a pool down to its max in the set: loads never clamp, and the max change rule of the rules decides what happens to Health when MaxHealth moves.

Changes

Change (server) works out the target with the ops of the contract from the clamped value (a base of 150 with Max 100 counts as 100), clamps it, and applies a transient instant effect of this attribute only: one AddBase modifier by the SetByCaller Pulse.Attribute.SetByCaller.Change. So the attribute set sees a normal effect (PostGameplayEffectExecute), and a change of Health never touches MaxHealth or Stamina. The effect context carries the Instigator and Source of the request (instigator, effect causer and source object), the Tags go in as dynamic asset tags. The answer is what the set did: After is read back.

Reset sets the start value of the rules (a pool without rules: its Max). Changes of other effects (weapon damage, a heal, a cost of an ability) send Changed with Cause External and the context of the effect: its instigator, the effect causer as Source, the asset tags of the spec as Tags. That holds also for a meta attribute: when the attribute set moves damage from IncomingDamage to Shield and Health in PostGameplayEffectExecute, GAS gives those changes no effect data, so the adapter takes the context of the effect that is executing (it listens to the unmapped attributes of the sets for it). A Max Attribute sends its Changed before the pools it bounds.

Code that changes attributes through GAS itself and wants its own context on the events opens a scope:

FPulseGASChangeScope scope(*Component, EPulseAttributeChangeCause::External, Context);
AbilitySystem->ApplyGameplayEffectSpecToSelf(Spec);

Scopes nest; the innermost one counts.

Modifier effects

Pulse modifiers on mapped attributes live in GAS as active effects, so abilities and other effects see the modified value. Each mapping needs an effect for that: Infinite, an AddBase modifier on the attribute by the SetByCaller Pulse.Attribute.SetByCaller.Add and a MultiplyAdditive one by Pulse.Attribute.SetByCaller.Multiply. The adapter sets both magnitudes on every spec (Add: m and 1; Multiply: 0 and 1 + m), which gives (Base + sum of Add) x (1 + sum of Multiply), the same numbers as the Pulse Attributes component.

The fix. The Set Up step Give every mapped attribute a modifier effect of Foundation checks every mapping. Its fix Create modifier effect creates a Blueprint GE_PulseModifier_<Attribute> per missing effect (in the folder of the map, else in /Game/Pulse/Attributes), enters it in the map and saves both. In C++, derive from UPulseAttributeModifierEffect and call Configure in the constructor:

UMyMaxHealthModifierEffect::UMyMaxHealthModifierEffect()
{
	Configure(*this, UMyHealthSet::GetMaxHealthAttribute());
}

What goes where:

Modifier In GAS
Value of a stat (armor, strength) An active effect of the mapping’s modifier effect.
Max of a pool with Max Attribute (Health up to MaxHealth) A Value modifier on the Max Attribute (MaxHealth), as the Pulse Attributes component does it.
Rate of a pool with rules In the rules, no effect.
Min, or Max of a fixed bound Refused with Pulse.Result.Failure.Invalid: the bounds come from GAS.
Value of a pool Refused with Pulse.Result.Failure.Invalid (a potion is a change).
Any modifier on a mapping without modifier effect Refused with Pulse.Result.Failure.Attribute.Refused; the text names the actor, the attribute, the map and the fix.

A modifier with the same attribute, target and source key replaces the old effect and keeps its id; the new effect goes on before the old one comes off, so the value never drops in between. Modify with List finds a Max modifier of Health under Health and under MaxHealth. Source keys of the form Band.<band>.<index> belong to the bands and are refused. A Duration runs on the game clock of the component (one timer for all, it waits while the game clock is paused); the effects themselves are Infinite and are removed when their time is over. Visible modifiers replicate with their end for the status bar.

Rules

GAS has no rates, bands or pause tags. A profile with Usage GAS Rules adds them to mapped attributes: set it as Rules on the component, or as Default Rules in Project Settings > Pulse > Foundation GAS. For mapped attributes only Rate, Rate Overrides, Pause Tags, Pause Mode, Bands, Max Change Rule and Visibility count; Min, Max, start and value come from GAS. A rule needs a rate or bands.

Implicit rules. A mapped pool that a Rate modifier of a band targets (the band Starving of PulseSurvival gives Pulse.Stat.Health a falling rate) gets a rule with rate 0 when the rules have none for it: the modifier then drains it without a Rules profile. The implicit rule is not saved and has no pause tags; a rule of your own wins. A rate 0 stays 0 under a Multiply modifier: to slow down regeneration (Fatigue halves the stamina rate), give the pool its rate in the rules. Problems of a binding (a rule without attribute set, a modifier that goes nowhere) are logged once per component, not again at every possession.

  • Rates without a tick. A running rate is written into the ASC through the change effect at every event (a band, an edge, full or empty) and at most every Update Interval seconds of the game clock (default 0.25). These writes send no Changed, like the rates of the Pulse Attributes component. Read always gives the exact value of the rate, also between two writes.
  • Effects from outside keep the rate. Damage of 20 between two writes gives the value read before minus 20; the part of the rate that was not written yet is not lost.
  • Bands put their tag and their granted tags on the ASC as loose tags (replicated as tags only), so abilities can require “Exhausted”. The adapter does not count its own loose tags as owner tags; the same tag from another system does count. GAS sends no tag event when the single-tag RemoveLooseGameplayTag takes a count from 2 to 1, so remove such a tag with RemoveLooseGameplayTags or through an effect (both send it); otherwise the adapter sees it at the next change of the owner tags.
  • Pause tags react to tag changes of the ASC at once. Tags of other components: call Notify Owner Tags Changed.
  • Max change rule. When the Max Attribute changes (a MaxHealth modifier), KeepValue, KeepFraction or AddGain moves the value and writes it into the ASC (Cause MaxRule).

Own attributes

Definitions of the rules or of plugins (Pulse::Attributes::RegisterDefinitions, see attributes of plugins) whose tag has no mapping are own attributes of the component: it keeps them in its rules like the Pulse Attributes component keeps them, with the full definition (bounds, start, rate, bands, modifiers). So hunger and thirst of a survival plugin run on a GAS player without a second source and without an attribute set.

Events and bPredicted

The adapter sends the same events and messages as every source (events and messages).

  • On the server every change of a mapped attribute sends Changed, then Depleted, Restored and RangeChanged where they apply; the context comes from the innermost change scope, else from the effect.
  • On clients, attributes with rules send Changed only from the replicated items of the component, never from the replicated ASC value, which often arrives in another frame: so there is no jump and no second Changed. Attributes without rules send the changes of the ASC value, bundled per frame: one Changed from the value before the first change of the frame to the value at its end (bPredicted if any change of the frame was), even before the first items arrive.
  • bPredicted is true on a client only while the ASC has a valid prediction key (ScopedPredictionKey): a change a predicted ability made. The effect data of GAS (GEModData) is never there on clients (instant effects do not run there, replicated base values come without it), so it plays no part. The server may still correct a predicted value; wait for the event without bPredicted before you show something final.

Saving

The component saves itself as bytes (IPulseByteSaveable, identity Pulse.Attribute.Save.GAS, with the player id for player actors): the attributes with rules and the own attributes, all mapped attributes with Save All Mapped, and the saved modifiers with their remaining time. A load applies the modifiers first (MaxHealth before Health), then sets the values with SetNumericAttributeBase, never clamped: 150 of 100 stays 150 as base. The max change rule does not run for the bounds a load or a reset moves: their own plan settles the values, and every event of a load (also of mapped attributes without rules) carries CatchUp Load. A reset removes the modifiers (a ModifiersChanged each) and sets the Max Attributes before the pools they bound.

Settings

Project Settings > Pulse > Foundation GAS (UPulseFoundationGASSettings):

Setting Default What it does
Default Map none The attribute map of every component without a map.
Default Rules none The rules of every component without rules (Usage GAS Rules).
Update Interval 0.25 s Game clock seconds between two writes of a running rate into the ASC.
GAS Attribute Component off Adds the component to every player state when it spawns.
Add Component When Ready on NotifyAbilitySystemReady adds the component to an ASC owner without one.

Debugging

  • Snapshot Attributes (GAS) of the component: the owner of the ASC, the map and rules, the mappings with their values, the active modifier handles and the rules (rates, bands, stamps).
  • The Pulse Debugger page Attributes shows the source as GAS.
  • The Check of Foundation reports Blueprints with an ASC but no component (while Add Component When Ready is off), Blueprints with both a Pulse Attributes and a Pulse GAS Attributes component, and rules whose Usage is not GAS Rules.

PulseFoundation plugin documentation.

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