Automatic component capture
Exactly which component state World State Reset Framework captures and restores automatically, what it deliberately leaves alone, and why.
When an Actor registers, WSRF takes a snapshot of it. A reset puts that snapshot back. This page states precisely what goes into the snapshot, what does not, and why.
Read this page before writing Custom State
Most integration mistakes come from re-implementing something the framework already restores, or from assuming it restores something it never claimed to. The tables below are the contract.
Actor level
Captured for every registered Actor, regardless of its components:
| Captured | Notes |
|---|---|
| Actor class | Used to recreate a destroyed placed Actor |
| Actor transform | Restored with TeleportPhysics |
| World origin | So world-origin rebasing does not shift restored positions |
| Hidden in game | |
| Actor-level collision enabled | |
| Actor tick enabled | |
| Actor tags | |
| Attachment to another Actor | Parent Stable ID, socket, relative transform |
Instance properties
WSRF also captures editable properties declared by the Actor’s own class when their value differs from the class default.
Supported types: booleans, numeric types, enums, FName, FString, FText, FVector,
FRotator, FTransform, FLinearColor, FColor.
Excluded by design: object references, arrays, maps, sets, and any struct not in the list above.
Inherited properties are not captured
Only properties declared by the Actor’s exact class are considered. For a Blueprint class deriving from a C++ Actor, the native properties are inherited and therefore skipped. Do not rely on this mechanism for gameplay values — use Custom State.
Component capturers
Component state is handled by typed capturers resolved through a per-world registry. A component is
matched by class, so a USkeletalMeshComponent is processed by the Scene, Primitive and Skeletal
capturers in that order. Each layer owns a distinct set of fields; no field is written twice.
| Capturer | Restored automatically | Not restored | Why |
|---|---|---|---|
| Scene (non-root) | Parent component and socket, relative transform, visibility for non-primitive scene components, activation, component tick | World transform, registration state, editor-only components, the root component’s transform | The Actor already owns the root/world transform; restoring it twice would fight itself |
| Primitive | Mobility, visibility and HiddenInGame, collision enabled, collision profile, responses that diverge from the profile, overlap generation, gravity, physics simulation, and velocities while simulating | Raw FBodyInstance, contacts, constraints, the Chaos scene, render buffers, velocities when not simulating | Restore a deterministic state without serialising the physics engine |
| Static Mesh | Static Mesh asset and material overrides | Mesh render internals and generated resources | Asset assignment and authored overrides are sufficient; generic shared fields belong to the Scene and Primitive layers |
| Skeletal Mesh | Skeletal Mesh asset, material overrides, Animation Mode, Anim Class; for Single Node: animation asset, loop, playing, play rate and position | Anim Instance, Animation Blueprint variables, per-bone pose, montage stack, cloth, full curves and morph targets, accumulated root motion, exact ragdoll pose | The authored animation setup is stable; internal runtime state is not. A ragdoll returns to the captured global simulation/animation state |
| Child Actor | Child Actor class, expected presence, and a marker when the child owns its own WSRF record | Instance pointer, recursive snapshot of the child, the child’s component graph | A child with its own Stable ID is an independent WSRF record; two authorities over one state is a defect |
| Audio | Sound asset, volume, pitch, Auto Activate, and the active/inactive state | Playback position, internal Sound Cue graph, concurrency, random seed, mixer state, virtualised voices | Deterministic contract: an active sound restarts at Play(0) rather than resuming approximately |
| Niagara | System asset, Auto Activate, and the active/inactive state | Live particles, CPU/GPU buffers, exact simulation age, Data Interfaces, bindings, user parameters | Unreal exposes no exact-resume API for a running simulation. The contract is active/inactive and restart |
The Niagara capturer is optional
It lives in the optional WorldStateResetFrameworkNiagara adapter module. The core runtime module
has no Niagara dependency, and the plugin does not force Niagara on projects that do not use it.
The included Demo loads the adapter because the Demo uses Niagara; a project that removes the Demo
but still wants Niagara capture must keep the adapter module, enable Unreal’s Niagara plugin, and
load WorldStateResetFrameworkNiagara before WSRF freezes its capturer registry for a game world.
Restore order
Capturers never choose their own ordering. The registry applies a fixed sequence:
- hierarchy and attachments
- relative transforms
- visual state and collision
- physics
- lifecycle — animation, audio, effects
This is why a parent component’s socket is valid before a child’s relative transform is applied, and why physics is re-enabled after the transform has already been set.
Rules the framework enforces
- Components are matched by stable name. There is no “there is only one component, use that one” fallback across different component types.
- A missing component is never recreated. If an updated Blueprint removed or renamed a component, WSRF reports it and moves on rather than fabricating an incomplete object.
- Every payload carries its capturer identity and version. A payload written by a capturer that is not registered, or by a newer version than the runtime supports, is ignored and reported. It is never reinterpreted.
- One bad payload never fails the whole restore. The remaining components still apply.
Measured cost
Measured capture, restore and persistence figures, per Actor profile — from a bare AActor up to a
fixture carrying all seven component families — are published in
Performance.
What stays yours
Automatic capture covers structural and visual state. It deliberately does not cover gameplay meaning:
- health, stamina, posture, status effects;
- AI state, blackboard, perception, targeting, boss phase;
- inventory, equipment and loot;
- quest and progression flags;
- cooldowns, abilities and combat state.
These require a rule to be applied, not just a value to be written back. Implement
WSRF Resettable and use Custom State.
Extending capture
A project can register its own capturer in C++ for a component type WSRF does not cover. See Extending capture.
Related pages
Last updated: 2026-09-04