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
- Create a Skill Progression asset (
Pulse > Skill > Skill Progression,UPulseSkillProgression). - 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. - Pick a
LevelCurveand add an entry toLevelRewardswith a Skill Points reward (the usual case). - Add the asset to
Progressionsof the skill component, or callAddProgressionat runtime. - 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:
Grantonce 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.Reapplyfor every level the progression already has, after a save was loaded and when the progression is added withAddProgression. 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 inReapply.
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,
Amount1. - 1 point per level up to 50, then 2: two entries,
ToLevel50 withAmount1 andFromLevel51 withAmount2. - A talent point every 5 levels: an entry with
FromLevel5 andEveryNLevels5, Skill Points withPointTagTalent.
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 = falseskips 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 withSend Gameplay Event To Actor.EventMagnitudeis the amount, the first tag ofTargetTagsthat is a progression of the component selects it (else the default progression), the first tag ofInstigatorTagsis the source. Can be switched off withbListenForExperienceEvents.
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) needsMinLevelin a progression, in a skill rank or any other Pulse condition list (a quest, a dialog choice). In a skill rank it fails withPulse.Skill.Failure.Level. - Events:
OnExperienceChanged(Component, ProgressionTag, Old, New)andOnLevelChanged(Component, ProgressionTag, OldLevel, NewLevel). On the authorityOnLevelChangedfires 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) andPulse.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 sendsPulse.Gameplay.Event.Skill.LevelChangedto its ability system once per level (EventMagnitudeis the new level, the progression tag is inInstigatorTags), 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 (FindProgressionresolves it). The variant needs the sameProgressionTag, 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
SetLevelorClearSkillState, 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
MaxLevelclamps 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::MaxLevelUpsPerSteplevels are gained in one step, as a guard against curves that do not grow.SetLevelwith 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.