Attributes

Module PulseAttributes (Gameplay Ability System). Health, shield and stamina as attribute sets that every Pulse plugin reads and changes through the attribute contract of Pulse Foundation, usable on their own: food that restores health, a potion, falling damage or a survival game without weapons need no combat system. The combat system (PulseCombat) builds on these sets.

Attribute sets

Set Attributes Notes
UPulseHealthAttributeSet Health, MaxHealth, Shield, MaxShield, meta IncomingDamage, IncomingHealing Damage takes the shield first, then health. Health 0 is never healed. The set clamps only at the bottom (see Clamping). The rules are pure functions on FPulseHealthPools (see below).
UPulseStaminaAttributeSet Stamina, MaxStamina For costs (normal GAS cost effects). Native event OnOutOfStamina.

Give a set to an ability system like any attribute set: a default subobject of the owner, AddAttributeSetSubobject, a PulseSkill grant, or Default Attribute Sets of the combat component (PulseCombat). Default Starting Data of the ability system component only creates sets that also have a data table. Both sets replicate to every client.

Pulse attributes

PulseAttributes registers both sets with the GAS adapter of Pulse Foundation in StartupModule (Pulse::Attributes::GAS::RegisterMappings, owner PulseAttributes):

Pulse attribute Gameplay attribute Kind Upper bound Modifier effect
Pulse.Stat.Health UPulseHealthAttributeSet.Health Pool Pulse.Stat.MaxHealth UPulseAttributeModifierEffect_Health
Pulse.Stat.MaxHealth UPulseHealthAttributeSet.MaxHealth Stat none UPulseAttributeModifierEffect_MaxHealth
Pulse.Stat.Shield UPulseHealthAttributeSet.Shield Pool Pulse.Stat.MaxShield UPulseAttributeModifierEffect_Shield
Pulse.Stat.MaxShield UPulseHealthAttributeSet.MaxShield Stat none UPulseAttributeModifierEffect_MaxShield
Pulse.Stat.Stamina UPulseStaminaAttributeSet.Stamina Pool Pulse.Stat.MaxStamina UPulseAttributeModifierEffect_Stamina
Pulse.Stat.MaxStamina UPulseStaminaAttributeSet.MaxStamina Stat none UPulseAttributeModifierEffect_MaxStamina

Health, MaxHealth, Stamina and MaxStamina are tags of Pulse Foundation (Pulse::Foundation::Tags::Stat_*); Shield and MaxShield are PulseGameplay’s own (Pulse::Attributes::Tags::Stat_Shield, Stat_MaxShield), and PulseAttributes registers them in the stat register. An entry with the same tag in the attribute map of a component or in the Default Map of the GAS adapter wins over these mappings.

So an actor with an ability system, one of the sets and the component Pulse GAS Attributes answers Pulse::Attributes::Read(Actor, Pulse.Stat.Health), Change, Modify, the Blueprint nodes Read Attribute, Change Attribute, Add Attribute Modifier, the conditions, costs and rewards of Pulse Foundation, HUDs and AI the same way as an actor with the Pulse Attributes component. Call Pulse::Attributes::GAS::NotifyAbilitySystemReady(Owner) after InitAbilityActorInfo (the combat component does it); it adds the component when it is missing (Add Component When Ready, on by default).

Clamping

Both sets clamp only at the bottom: Health and Shield at least 0, MaxHealth at least 1, MaxShield, Stamina and MaxStamina at least 0. The upper bound belongs to the GAS adapter:

  • Reading clamps: Read gives Health clamped to MaxHealth (Value) and the stored value as Base.
  • Changes through the contract (Change) clamp their result to the bounds.
  • A lower maximum never pulls the stored value down; the max change rule of the rules (KeepValue, KeepFraction, AddGain) decides what happens to Health when MaxHealth moves.
  • A load is never clamped: a saved 150 of 100 stays 150 as base and reads as 100.

Damage and healing through IncomingDamage and IncomingHealing work on the values clamped to their maximum, like Change. Code that reads the gameplay attributes directly (GetNumericAttribute) can see a value above the maximum; read through the contract instead.

Damage and healing without combat

  • Damage: any instant effect that adds to IncomingDamage. The set reports what happened with OnDamageReceived (FPulseHealthChange: amount, shield part, health lost, shield broken, depleted, instigator, causer, location) and OnOutOfHealth once when health reaches 0. A system on top can attach own data with SetPendingPayload right before the damage is applied; it arrives as FPulseHealthChange::Payload (PulseCombat sends its FPulseDamageResult this way).
  • Healing: Pulse::Combat::ApplyHealing with PulseCombat (Blueprint Apply Healing: the dead are not healed), or without combat Pulse::Attributes::Change with Op Add on Pulse.Stat.Health (Blueprint Change Attribute). Own gameplay effects that add to IncomingHealing still work; OnHealingReceived reports only those.
  • Regeneration: a rate of the rules of the GAS adapter, not an effect. Give Pulse.Stat.Health or Pulse.Stat.Stamina a Rate in a profile with Usage GAS Rules (the Rules of the Pulse GAS Attributes component, or Default Rules in Project Settings > Pulse > Foundation GAS); its Pause Tags pause it (the combat component puts its death tag on the owner). Set its Pause Mode to GainOnly, so the pause holds only the regeneration and a drain (starving) goes on. See Rules.

The tuning knob Pulse.Tuning.Attributes.RateGain of Pulse Foundation multiplies rising rates (regeneration); losses through a falling rate stay. The old knob Pulse.Tuning.Attributes.Regeneration is redirected to it.

Attributes that change on the game clock

Hunger and thirst that fall, oxygen that falls under water, mana that fills: attributes that change on their own over game time are part of the attribute contract of Pulse Foundation, not of PulseAttributes. A definition (FPulseAttributeDefinition) gives an attribute a Rate per second, minute or hour of the game clock, RateOverrides by tags of the owner, PauseTags and Bands with a tag, granted tags and modifiers while the value is in them. See Profiles and store.

  • With GAS (the sets of PulseAttributes): give the attribute a rate or bands in a profile with Usage GAS Rules (the Rules of the Pulse GAS Attributes component, or Default Rules in Project Settings > Pulse > Foundation GAS). Attributes without an attribute set (hunger of a survival plugin) are own attributes of the component. See Rules and Own attributes.
  • Without GAS: the same definition in the profile of the Pulse Attributes component.
  • From a plugin: Pulse::Attributes::RegisterDefinitions in StartupModule adds attributes to every profile (an entry of the profile wins), so the plugin works without a change to the project’s profiles.
  • Damage while empty (starving, drowning) is a band at 0 whose modifier gives Pulse.Stat.Health a negative Rate; death is Depleted of health, as in combat.

The tuning knob Pulse.Tuning.Attributes.RateLoss of Pulse Foundation multiplies falling rates; the old knob Pulse.Tuning.Attributes.BarDecay is redirected to it.

The bars of PulseAttributes (the Pulse Bars component, the Pulse Bar asset and Pulse::Attributes::Bars) are gone; see Coming from PulseCore 1.x. The attribute bars of Status effects and attribute bars only show attributes on the HUD.

Health rules without an ability system

FPulseHealthPools (Attributes/PulseHealthPools.h, no GAS include) holds health, maximum health, shield and maximum shield as plain values. The rules of the health set are functions in Pulse::Attributes: ClampHealth, ClampMaxHealth, ClampShield, ClampMaxShield, ApplyDamageToPools (shield first, never below 0, the dead take nothing; fills an FPulseHealthChange), ApplyHealingToPools (up to the maximum, the dead are not healed) and DescribeAppliedDamage. PulseCombat uses ApplyDamageToPools for targets with a Pulse Attributes component and a shield, so both damage paths share one rule. Targets without an ability system (build pieces, resource nodes) use them for the same behavior. The set plans with them and reports the values it reads back, so duration and infinite modifiers count (a temporary shield that stays above 0 is not broken). Specs: PulseAttributes.Pools, and PulseAttributes.Parity (the same steps against the health set through the GAS adapter and against the Pulse Attributes component give the same values).

Replication: the sets replicate with the push model. Ability system writes, base value changes (PostAttributeBaseChange) and InitFromMetaDataTable (Init Stats) mark the attributes; code that calls an Init<Attribute> accessor after the first replication must mark the attribute itself (MARK_PROPERTY_DIRTY), or set it through the ability system instead.

View models

Attribute view models are part of Pulse Foundation: UMVVMPulseAttributeValue (module PulseFoundationMVVM) shows one Pulse attribute of any source by its tag (Attribute, e.g. Pulse.Stat.Health): Value, MaxValue, MinValue, Base, RatePerSecond, Band, bDepleted, DisplayName, Icon, GetPercent and HasAttribute. With the Pulse Player View Model Resolver it follows the player’s pawn, also after respawns; SetSource shows any actor. It follows the events of the source, so no ready call is needed for it. The Pulse Attribute Bar of Status effects and attribute bars is built on it.

The view model UMVVMPulseAttribute of PulseAttributes is gone; a class redirect moves Blueprint subclasses and bindings to UMVVMPulseAttributeValue (see Coming from PulseCore 1.x).


PulseGameplay plugin documentation.

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