Progression (experience and levels)

A progression turns experience into levels, and levels into rewards such as skill points. It is part of UPulseSkillComponent, so it replicates, saves and loads together with the skills. A component can have several progressions, e.g. a character level and a weapon mastery.

AddExperience(Progression, Amount, Source)     ← your game code, UPulseSkillLibrary or a gameplay event
  └─ experience modifiers   (multipliers, e.g. double experience buff)
  └─ tuning                 (Pulse.Tuning.Reward of the kind Pulse.RewardKind.Experience, e.g. a difficulty)
  └─ experience += amount   (stops at the highest level)
  └─ while experience reaches the next level:
        level + 1  →  OnLevelChanged  →  level rewards of that level (e.g. skill points, a skill tree)

Level curves and experience modifiers are inline objects in the progression asset: pick one of the built-in classes or write your own in C++ or Blueprint. Every gain is also tuned by the tuning knob Pulse.Tuning.Reward of PulseFoundation with the kind Pulse.RewardKind.Experience, also without the modifiers (the progression tag and the source tag are in the tags, so a value can change one progression or one source only). Level rewards are Pulse rewards (Pulse Foundation), the same entries a skill rank, a quest or an achievement gives.

Setup

  1. Create a Skill Progression asset (Pulse > Skill > Skill Progression, UPulseSkillProgression).
  2. Set a unique ProgressionTag (saved and replicated, do not change it after release). If you only have one progression, use the default tag of the settings (Pulse.Skill.Progression.Default), then every function works with an empty tag.
  3. Pick a LevelCurve and add an entry to LevelRewards with a Skill Points reward (the usual case).
  4. Add the asset to Progressions of the skill component, or call AddProgression at runtime.
  5. Give experience on the authority: AddExperience(ProgressionTag, Amount, SourceTag).

Example: a character level up to 20 with the default formula curve (100, 283, 520, … experience) and one skill point per level. It uses the tag Progression.Example.Character from the example tag table; the example player state of Getting started gives experience with Add Experience.

Asset properties

Property Description
ProgressionTag Stable id.
DisplayName, Description, Icon For UI.
StartLevel Level with 0 experience (default 1). It gets no rewards; use StartingSkillPoints of the component for that.
MaxLevel Highest level, 0 means no limit. Experience stops growing at the highest level.
LevelCurve How much total experience each level needs (UPulseSkillLevelCurve).
LevelRewards What reaching a level gives: entries with a level filter and Pulse rewards (FPulseSkillLevelRewardEntry).
ExperienceModifiers Multipliers for given experience (UPulseSkillExperienceModifier).

Helpers: GetExperienceForLevel(Level), GetLevelForExperience(Experience), IsMaxLevel(Level), GetMaxExperience(), ClampLevel(Level), GetRewardDescriptions(Level). Data validation checks the tag, empty entries and that the curve grows for the first 100 levels.

Experience in the stat register

Every progression registers its experience as a Counter of the stat register of Pulse Foundation when the asset is loaded (and again when it changes in the editor): the tag is ProgressionTag, with DisplayName, Description, Icon and the category Skills (MakeExperienceStat). The progression view model takes the name from the register, so a project can rename a progression in Project Settings > Pulse > Foundation > Stats without touching the asset.

Level curves

A level curve returns the total experience a level needs, counted from the start level (0). It must grow with the level; a level that cannot be reached returns MAX_int32.

Class Display name Description
UPulseSkillLevelCurve_Formula Formula Base * n ^ Exponent + Linear * n, n = levels above the start level. Default: 100, 1.5, 0 (100, 283, 520, … ).
UPulseSkillLevelCurve_Table Table List of totals, entry 0 is the first level above the start level. After the list ExperiencePerLevelAfterTable more per level, or the end of the progression if 0.
UPulseSkillLevelCurve_Curve Curve Float curve (inline or curve asset), evaluated at the level itself.

Own curve: subclass UPulseSkillLevelCurve and override GetExperienceForLevel(Progression, Level).

Level rewards

LevelRewards is a list of entries (FPulseSkillLevelRewardEntry). Every entry has a level filter and a list of Pulse rewards: the rewards are given for level L if L >= FromLevel, L <= ToLevel (0 = no limit) and (L - FromLevel) is a multiple of EveryNLevels. The defaults give them for every level.

Any Pulse reward works (items of Pulse Gameplay, a quest of Pulse Quest, …). Pulse Skill brings:

Reward Description
Skill Points (FPulseReward_SkillPoints) Amount points of PointTag (empty = default pool), or the points of the curve AmountByLevel at the level that is reached if bUseAmountByLevel is on.
Skill Tree (FPulseReward_SkillTree) Adds Tree to the component. Set FromLevel of the entry to the level that unlocks it.
Experience (FPulseReward_Experience) Experience for another progression (or the same one).
Skill Rank (FPulseReward_SkillRank) Raises a skill to a rank.

The context of a level reward: the owner of the component as Player, the progression as Source, the level as Amount, the source of the experience in Tags and FPulseSkillProgressionContext as extra data. The component calls the rewards on the authority:

  • Grant once for every level that is reached, in level order. Its result must be saved by something else (skill points are saved by the component), because it is not called again after loading.
  • Reapply for every level the progression already has, after a save was loaded and when the progression is added with AddProgression. Rewards whose result is not saved use it: skill trees are not saved, so Skill Tree adds its tree again here. Most rewards do nothing in Reapply.

GetRewardDescriptions(Level) returns the lines for UI (“1 Skill Point”, “Skill tree Fire Magic”).

Examples:

  • 1 skill point per level: one entry with Skill Points, Amount 1.
  • 1 point per level up to 50, then 2: two entries, ToLevel 50 with Amount 1 and FromLevel 51 with Amount 2.
  • A talent point every 5 levels: an entry with FromLevel 5 and EveryNLevels 5, Skill Points with PointTag Talent.

Experience modifiers

When experience is given with modifiers (the default), the amount is multiplied with the multiplier of every modifier and rounded. Negative multipliers count as 0.

Class Display name Description
UPulseSkillExperienceModifier_OwnedTags Owned Tags Multiplier while the ability system meets TagRequirements (e.g. a double experience buff).
UPulseSkillExperienceModifier_Attribute Attribute BaseMultiplier + Attribute * Scale; Attribute is a Pulse.Stat tag read from the attribute source of the owner (Pulse::Attributes::Read, with or without GAS). The defaults treat the attribute as bonus (0.25 = +25%); without the attribute the multiplier is 1.
UPulseSkillExperienceModifier_Source Source Multiplier for experience whose source tag matches SourceTags (child tags match).

Own modifier: subclass UPulseSkillExperienceModifier and override GetMultiplier(Context). ApplyExperienceModifiers(ProgressionTag, Amount, SourceTag) on the component shows the result without giving the experience, e.g. for a preview.

Giving experience

All of these run on the authority; the source tag is optional and only used by modifiers and rewards.

  • C++ / Blueprint: SkillComponent->AddExperience(ProgressionTag, Amount, SourceTag). Returns the experience that was added (after modifiers and the highest level). bInApplyModifiers = false skips the modifiers.
  • Any actor: UPulseSkillLibrary::AddExperience(Actor, ProgressionTag, Amount, SourceTag) finds the component of a pawn, controller or player state.
  • Gameplay event: send Pulse.Gameplay.Event.Skill.Experience (or a child tag) to the ability system of the component, e.g. from an ability with Send Gameplay Event To Actor. EventMagnitude is the amount, the first tag of TargetTags that is a progression of the component selects it (else the default progression), the first tag of InstigatorTags is the source. Can be switched off with bListenForExperienceEvents.

Other functions:

Function Description
SetLevel(ProgressionTag, Level, bGiveRewards) Sets the level (clamped) and the experience that level needs. With bGiveRewards the rewards of every level in between are given, one level at a time: the state is read again after every level, so a level reward that gives experience is kept, no level is rewarded twice and the level never goes down. Each step sets the experience to what the next level needs, as SetLevel without rewards does (unless the experience is already above it); it can end above the target when a reward gives enough experience. A lower level takes nothing back.
AddProgression / RemoveProgression Change the progressions at runtime. A removed progression keeps its state but gains no levels.
GetExperience, GetLevel, GetExperienceForLevel, GetLevelProgress, IsMaxLevel Queries. GetLevelProgress is 0 to 1 between the current and the next level.
GetProgressionStates Experience and level of every progression that has a state.

Without experience a progression has no state yet; GetLevel returns its start level.

Using the level

  • Condition: Level (FPulseCondition_SkillLevel) needs MinLevel in a progression, in a skill rank or any other Pulse condition list (a quest, a dialog choice). In a skill rank it fails with Pulse.Skill.Failure.Level.
  • Events: OnExperienceChanged(Component, ProgressionTag, Old, New) and OnLevelChanged(Component, ProgressionTag, OldLevel, NewLevel). On the authority OnLevelChanged fires once per level, right before the rewards of that level; on clients after replication.
  • Messages: Pulse.Message.Skill.LevelChanged (once per level change, also on clients) and Pulse.Message.Skill.ExperienceGained (experience that was added, on the authority and the owning client; not for loaded or set experience). See Skill component.
  • Gameplay event: if enabled (bSendGameplayEventOnLevelChange), the component sends Pulse.Gameplay.Event.Skill.LevelChanged to its ability system once per level (EventMagnitude is the new level, the progression tag is in InstigatorTags), e.g. for a level-up effect.
  • UI: UMVVMPulseSkillComponent::Progressions / DefaultProgression, see MVVM and UI.

In the editor

A progression opens in the config workshop. Its preview Curve shows the experience per level: the total as a line, the step from the level before as bars, and the levels with rewards (select a reward entry to mark only its levels). Below it a table lists level, total, step and the reward descriptions; Levels shown sets how many levels it reads (a curve without a highest level goes on). Specs: PulseSkill.Editor.ProgressionPreview.

Difficulty

A difficulty (Pulse Difficulty or any tuning source) changes a progression in three ways:

  • Experience: every gain is a reward amount of the kind Pulse.RewardKind.Experience (Pulse::Rewards::GetAmount, the progression tag and the source tag in the context tags), so the reward tuning scales it.
  • Rank costs: the costs of skill ranks carry the cost kind Pulse.CostKind.Skill, so the cost tuning scales them.
  • Another progression: a Swap adjustment (FPulseAdjustment_Swap) with this progression as Original uses a variant instead (FindProgression resolves it). The variant needs the same ProgressionTag, otherwise the original stays, so saved experience and levels keep fitting; make it a variant of the original in the workshop.

Rules

  • Experience never goes down, and levels are never taken away (except by SetLevel or ClearSkillState, which take no rewards back either).
  • Every level is rewarded once. The level is saved, not derived from the experience, so changing the curve later does not give rewards twice: players with enough experience for more levels get them the next time experience is given, the save is loaded or the progression is added. A lowered MaxLevel clamps saved levels on load.
  • A reward can give experience itself (to the same or another progression); the level-up loop reads the state again after every level. At most UPulseSkillProgression::MaxLevelUpsPerStep levels are gained in one step, as a guard against curves that do not grow. SetLevel with rewards does the same: it raises the level one at a time, each step sets the experience to what the next level needs, and it reads the state again after the rewards of each level, so a reward that gives experience never makes a level come twice or go down (and the level can end above the target).
  • Clients read the replicated state; the curves also run on clients for UI. Experience is only given on the authority, there is no client request for it.
  • The curve and level rules are pure functions in Pulse::Skill (Rules/PulseSkillProgressionRules.h: CapExperience, NextLevelUp, NextSetLevelStep, GetLevelProgress, …) that the component calls; they run on the game thread (curves and modifiers are Blueprint events).

Save and load

FPulseSkillSaveData::Progressions (format version 2) keeps tag, experience and level of every progression. Version 1 data still loads. See Save and load.


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