Skill component

UPulseSkillComponent holds the skills of one player. Add it to any actor; the player state is recommended because it survives respawns.

Setup properties

Property Description
SkillTrees Trees the player can use. Replicated. Change at runtime with AddSkillTree / RemoveSkillTree.
StartingSkillPoints Points per pool, given once on the authority in BeginPlay (not again after a save was loaded).
Progressions Progressions (experience and levels) of the player. Replicated. Change at runtime with AddProgression / RemoveProgression.
ReplicationMode Default (the owning client), OwnerOnly or Everyone (EPulseReplicationMode). Set it in the defaults, it is read once.

Example: a player state with the component, an ability system component, the example tree and progression, one starting skill point and handlers for OnSkillRankChanged, OnLevelChanged and OnRequestFailed. See Getting started for how to try it.

Unlocking

TryUnlockSkill(Tag) raises a skill by one rank. On the authority it calls UnlockSkill; on a client it checks locally and sends a server RPC. A rank can be unlocked when:

  1. the tag is valid and the skill is in one of the SkillTrees (Pulse.Skill.Failure.NotInTree),
  2. it does not have its highest rank yet (MaxRank),
  3. the prerequisites of its tree node are met (Prerequisite),
  4. all conditions of the rank pass (Requirement, or Level for a Level condition; the message is the line of the first condition that does not pass),
  5. all costs of the rank can be paid (Cost, “Not enough …”).

Every failure is an FPulseResult with one of these reasons. Its text for the player (Get Display Text) is the text the plugin registered for the reason; replace it in the Result Texts of Pulse Foundation (Project Settings > Pulse > Foundation). Placeholders come from FPulseSkillFailureDetails: {Other} (the other skill or what is missing) and {Rank}.

Then the unlock runs as one exchange of PulseFoundation, all or nothing: the conditions and costs of the rank are checked again, the costs are paid, the rank is raised (the grants are applied), and the rewards of the rank are given the first time the rank is unlocked. A reward that cannot be given (Give Items without dropping and no room) stops the unlock with Rewards; a step that fails while running takes back what ran before it (rank, rewarded rank, costs). On the server a condition or cost that answers “data missing” stops the unlock as well. The events of the component (rank, points, progress, state, the gameplay event of the rank) wait until everything is written and then fire in the order of the writes. CanUnlockSkill runs the checks without changing anything, for UI. See Conditions, costs, rewards and grants.

In C++, Pulse::Skill::CheckUnlock (Rules/PulseSkillRules.h) runs the same checks without a component, against a Pulse::Skill::FStateView over plain save data: for tools, tests and exchanges that plan a state first.

The unlock as an exchange (C++)

Pulse::Skill::MakeUnlockExchange(Plan) (Rules/PulseSkillExchange.h) builds the FPulseExchange of an unlock plan without changing anything and without a world: one party (MakeContext of the plan), the steps Conditions and Costs of the rank (Take), FPulseSkillExchangeStep_Rank (Give: sets the rank on the component of the plan, marks it as rewarded, Undo sets both back) and Rewards when the plan gives them (Pulse::Skill::UnlockStep names the indices). Add steps of your own (an item of a trader, a fee) and run it with Pulse::Exchange::Run; Pulse::Skill::MakeUnlockFailure turns a failed result into the FPulseSkillFailure of UnlockSkill. To hold the events of the component around your own exchange, keep an FPulseSkillEventHold alive while it runs.

// Owner: FPulseSkillContext with Component = Skills (and its ability system and owner)
const FPulseSkillRankPlan plan = Pulse::Skill::CheckUnlock(Skills->SkillTrees, Tag, GetRank, Skills->GetRewardedRank(Tag), Owner);
if (plan.CanApply())
{
	FPulseExchange exchange = Pulse::Skill::MakeUnlockExchange(plan);
	exchange.AddStep<FPulseExchangeStep_Costs>(0).Costs = TrainerFee;

	FPulseSkillEventHold hold(Skills);
	const FPulseSkillFailure failure = Pulse::Skill::MakeUnlockFailure(plan, Pulse::Exchange::Run(exchange));
}

Refunds and resets

  • TryRefundSkill / RefundSkill lowers a skill by one rank and refunds the costs of that rank (rewards are not taken back, and unlocking the rank again does not give them again: GetRewardedRank). It fails if the skill has bCanRefund off (NotRefundable) or an unlocked skill of a tree needs the current rank as prerequisite (HasDependents). In C++, Pulse::Skill::PlanRefund runs the same checks without a component (with a rank query or a state view).
  • ResetTree(TreeTag) and ResetAllSkills() set skills to rank 0 (respec). They ignore bCanRefund and prerequisites and refund all ranks unless bInRefundCosts is false. Clients can request them with TryResetTree / TryResetAllSkills if the settings allow it.
  • SetSkillRank sets a rank directly, without conditions, costs and rewards, e.g. for quest rewards and cheats. It also works for skills that are in no tree.
  • ClearSkillState removes all ranks, points and the experience and level of all progressions, without refunding anything.

Skill points

Function Description
AddSkillPoints(PointTag, Amount) Adds (or removes, if negative) available points.
SpendSkillPoints / RefundSkillPoints Move points between available and spent. Used by the skill point cost.
GetSkillPoints / GetSpentSkillPoints Current values of a pool.
GetPointsSpentInTree(Tree, PointTag) Points the unlocked ranks of a tree cost, from their skill point costs.

An empty point tag always means the default pool of the settings.

Experience and levels

AddExperience(ProgressionTag, Amount, SourceTag) gives experience to a progression; every level it reaches gives its level rewards once, e.g. skill points. SetLevel, GetExperience, GetLevel, GetLevelProgress and IsMaxLevel complete it. The component also gives experience for the gameplay event Pulse.Gameplay.Event.Skill.Experience on its ability system. See Progression.

Finding the ability system

Grants are applied to one UAbilitySystemComponent. FindAbilitySystemComponent (overridable in C++ and Blueprint) looks for it:

  1. on the owner (IAbilitySystemInterface or a component),
  2. for a player state owner, on its pawn.

The component looks again in BeginPlay and one tick after the pawn of an owning player state changed (possess, respawn). When the ability system changes, all grants are removed from the old one (if it still exists) and applied to the new one. For other setups call SetAbilitySystemComponent or RefreshAbilitySystem yourself. ReapplyGrants removes and applies everything again.

Without an ability system only the grants that do not need one are applied (Grant Attribute Modifier, the grants of PulseSkillInventoryBridge). On the authority the component watches the attribute events of its owner (UPulseAttributeSubsystem::WatchActor): when a source is ready or its modifiers changed, and one tick after the pawn of an owning player state changed, it asks every applied grant NeedsReapply and applies those again (an attribute modifier on a new pawn, after a load or a reset).

Events

Event When
OnSkillRankChanged(Component, Skill, OldRank, NewRank) A rank changed. On clients after replication.
OnSkillPointsChanged(Component, PointTag, Available) Available points of a pool changed.
OnRequestFailed(Component, Skill, Failure) A request failed, on the machine that sent it.
OnSkillTreesChanged(Component) The trees changed.
OnSkillStateChanged(Component) Anything changed; once per operation or replication update. Good for refreshing UI.
OnAbilitySystemChanged(Component, AbilitySystem) The ability system the grants go to changed.
OnExperienceChanged(Component, ProgressionTag, OldValue, NewValue) The experience of a progression changed.
OnLevelChanged(Component, ProgressionTag, OldValue, NewValue) The level of a progression changed; on the authority once per level.

Each event has a native version with the suffix Native (e.g. OnSkillRankChangedNative).

If enabled in the settings, the component also sends the gameplay event Pulse.Gameplay.Event.Skill.RankChanged to the ability system on the authority (EventMagnitude is the new rank, the skill tag is in InstigatorTags), so abilities can react with Wait Gameplay Event. Pulse.Gameplay.Event.Skill.LevelChanged works the same way for progression levels.

Finding the component

UPulseSkillLibrary::GetSkillComponent(Actor) works for pawns, controllers, player states, actors owned by them (weapons, equipment) and any actor with the component. Implement IPulseSkillOwnerInterface on actors that know their component to make the lookup explicit.

Messages

Besides its events, the component broadcasts on the PulseFoundation message bus, so other systems (a HUD, quests, achievements, sounds) can react without a reference to it. Every message has a context: the owner of the component is the Player.

Channel Payload Context Where
Pulse.Message.Skill.RankChanged FPulseSkillRankChangedMessage (component, skill, old rank, new rank) the skill as Source, its tag in Tags, the new rank as Amount authority and clients
Pulse.Message.Skill.PointsChanged FPulseSkillPointsChangedMessage (component, point tag, available points) the pool in Tags, the available points as Amount authority and clients
Pulse.Message.Skill.LevelChanged FPulseSkillLevelChangedMessage (component, progression, old level, new level) the progression as Source, its tag in Tags, the new level as Amount authority and clients
Pulse.Message.Skill.ExperienceGained FPulseSkillExperienceGainedMessage (component, progression, gained amount, experience now, source tag) the progression as Source, its tag and the source tag in Tags, the gained experience as Amount authority and owning client

Rank, point and level messages also come from loading and from the first replication on a client. Their context says so: CatchUp = Load while save data is applied (the messages also carry bFromSaveData, on the authority while IsLoadingSaveData() is true), and on a client the state of its first replication (CatchUp Replication or Join). A HUD that shows toasts leaves these out. The PulseSkillHUDBridge plugin does: its toasts go to the UI host of the player (ShowNotification of the PulseFoundation presenter, the Pulse HUD by default) with the kinds Pulse.UI.Notification.Skill.*, and the skill menu opens on the layer Pulse.UI.Layer.Menu of that host. ExperienceGained only comes for experience that was added (AddExperience, rewards, experience events), not for loaded or set experience; the owning client gets it through an unreliable RPC, so it can be missing on a bad connection while the experience itself always replicates.

Debugging

  • Tools > Debug > Pulse Debugger > Live (and the gameplay debugger category Pulse for the selected actor) shows every skill component: authority, ability system, trees, ranks, points and progressions.
  • Rank and point changes are events on the Timeline page (source Skill).

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