How-To: Persist Combat State Across Levels
Goal: keep buffs, cooldowns and attribute values across a ServerTravel instead of resetting the player every time they walk through a door.
How it works
A UCrimsonAbilityStateCarrierSubsystem (a game instance subsystem, so it outlives the world) holds a snapshot between levels. The old world stashes; the new world consumes.
1. Choose what persists
Tag your effects with Crimson.Persistence.Persist to opt in, or Crimson.Persistence.DoNotPersist to opt out, then set the default policy in Project Settings -> Crimson -> Ability State Persistence. Loose tags added by game code can be kept out of the snapshot with Excluded Loose Tags in the same settings - matched hierarchically, so excluding a parent tag excludes every child under it. The exclusion applies on restore too, which heals snapshots taken before a tag joined the list.
| Never captured | Why |
|---|---|
| Effects granted by an ability set or equipment | The loadout re-grants them next session. Capturing them too would apply them twice. |
| Instant effects | Their result is already baked into the attribute base values, which are captured. |
| Effects built at runtime | A NewObject<UGameplayEffect> has no class of its own - its configuration lives on that one instance, so only the bare UGameplayEffect would be stored and nothing could be rebuilt from it. Author a real GE asset for anything that must survive a save. |
Tags an active ability holds via ActivationOwnedTags | They end with the ability, and nothing re-applies them after travel - capturing them would bring them back as permanently stuck loose tags (a lock-on state tag outliving the lock-on, for example). The capture tallies what every active ability is holding and subtracts it automatically. |
| Loose tags listed under Excluded Loose Tags | The project's own escape hatch for transient status tags added by game code that must not survive a travel. |
2. Stash and restore
Get Game Instance Subsystem (CrimsonAbilityStateCarrierSubsystem) then Stash Snapshot before travel and Consume Snapshot after the new level loads. Has Snapshot and Peek Snapshot let you check without consuming.
3. Effect-level persistence
UCrimsonEffectPersistenceComponent handles the per-effect bookkeeping if you want persistence without driving the carrier yourself. Add it to the actor that owns the ASC.
See also
- Concept: Ability System Component
- Concept: Multiplayer and Prediction