Save and load

Pulse Skill does not depend on a save system. The component exports its state as a struct or as bytes and saves itself as bytes (IPulseByteSaveable), so PulseSave keeps it without a bridge.

What is saved

FPulseSkillSaveData:

Field Description
Version Format version (FPulseSkillSaveData::CurrentVersion, now 4). Newer versions are rejected (by LoadDataFromBytes and by ImportSaveData), older ones load.
Skills Skill tag and rank of every unlocked skill, with the cost factor each rank was paid with (CostFactors, since version 4; missing ones count 1).
Points Point tag, available and spent points of every pool.
Progressions Progression tag, experience and level of every progression (since version 2).
RewardedRanks Highest rank per skill whose rewards were given, also for skills refunded to rank 0 (since version 3). Data of older versions counts its saved ranks as rewarded.

The skill trees and progression assets are not saved: they are part of the game setup (component defaults, or AddSkillTree / AddProgression from your code, which you restore yourself). Trees given by a Skill Tree level reward are restored by the reward (Reapply).

Functions (authority only)

Function Description
ExportSaveData(OutData) Collects ranks, points and progressions.
ImportSaveData(Data, OutReport) Replaces ranks, points and progressions and applies the grants. Returns false for data of a newer version and then changes nothing, also not the setup (starting points come as for a new player). Do not save the component over rejected data: the newer data would be lost.
SaveToBytes(OutBytes) ExportSaveData + Pulse::Skill::SaveDataToBytes.
LoadFromBytes(Bytes, OutReport) Pulse::Skill::LoadDataFromBytes + ImportSaveData.
IsLoadingSaveData() True while ImportSaveData applies the state.

The bytes are written with tagged property serialization; gameplay tags are stored by name.

Loading rules

  • Conditions and costs are not checked and rank rewards are not given, the saved state is trusted.
  • Entries with an invalid tag or a rank of 0 or less are skipped (SkippedSkills).
  • A skill or a point pool that the data lists twice loads once: the first entry wins, the others are skipped with a message (a skill counts in SkippedSkills). A skill listed twice in RewardedRanks keeps its highest rank.
  • Ranks above the highest rank of a skill are clamped, with a message.
  • Skills that are in no tree of the component keep their rank (UnresolvedSkills). Their grants are applied as soon as a tree with them is added. So the order “load skills, then add unlocked trees” works as well as the other way round.
  • StartingSkillPoints are not given after a load.
  • A load changes only what differs: skills, pools and progressions that stay the same keep their replicated items, so clients get only the changes. After a load the ranks, pools and progressions are in the order of the data (ExportSaveData gives the loaded data back in its order).
  • Progressions: experience and level are restored without rewards (the skill points they gave are in Points). Levels of progressions of the component are clamped to their MaxLevel. Then, for every progression of the component, Reapply of the level rewards runs for the saved levels, and levels the experience reaches with the current curve are given with their rewards. Progressions the component does not have keep their state until they are added with AddProgression, which does the same.
  • Events: OnSkillRankChanged for every rank that differs from before, OnSkillPointsChanged for every pool, OnExperienceChanged / OnLevelChanged for every progression that differs, then OnSkillStateChanged. They come while IsLoadingSaveData() is true, and the messages of the load carry bFromSaveData, so a HUD shows no toasts for loaded skills.

Checking save data

The load runs in three pure steps (Rules/PulseSkillLoadState.h) that C++ code can also call without loading:

  • Pulse::Skill::BuildLoadState(Data, Trees, Progressions) checks, clamps and migrates the data into the state a component with these trees and progressions would have (FPulseSkillLoadPlan: bAccepted, State, Report). It changes nothing; bAccepted is false for data of a newer version.
  • Pulse::Skill::CaptureState(...) turns live state into save data (what ExportSaveData writes).
  • Pulse::Skill::DiffState(Old, New, Progressions) lists what differs between two states.

ImportSaveData is BuildLoadState, then DiffState against the current state, then one write of the whole state, then the events.

PulseSave

The component implements IPulseByteSaveable of Pulse Foundation: PulseSave keeps it in its general byte model with the byte collector of PulseSave (the Set Up step “Let the save menus save objects that save themselves as bytes”). No bridge is needed.

  • The save identity is Pulse.Skill.Save.Skills (SaveIdentity on the component): on a player state the key is Player.<player id>.Pulse.Skill.Save.Skills, the same in every session. A second skill component on the same actor needs its own SaveIdentity.Key.
  • Only the authority saves. ResetToDefaults (the carry rule Reset of a respawn) loads empty save data: no ranks, and the points and levels a new component gets.
  • Problems while loading show up as warnings in the PulseSave reports.
  • Saves of the archived PulseSkillSaveBridge (model UPulseSkillSaveModel) are not read anymore (Pulse Skill was not released yet).

Other save systems

// Save
TArray<uint8> bytes;
skills->SaveToBytes(bytes);
MySaveGame->SkillBytes = bytes;

// Load (on the authority)
FPulseSkillImportReport report;
skills->LoadFromBytes(MySaveGame->SkillBytes, report);

Or use ExportSaveData / ImportSaveData and store the struct in a USaveGame.


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