World State Reset Framework

Designed for souls-like, action RPG, roguelite, dungeon crawler and checkpoint-driven games.

Overview

World State Reset Framework (WSRF) restores selected parts of an Unreal Engine world to a known state without requiring a full level reload.

Actors can respawn after destruction, return to captured transforms and configuration, preserve permanent changes, retain one-shot state, or participate in custom gameplay restoration.

The whole setup is one component and two choices:

Add WSRF State Component -> Pick Preset -> Pick Region -> Play

Three behaviours

Resettable — the Actor returns when a matching world or region reset occurs. Enemies, traps, breakable props, resettable doors.

Persistent — the Actor keeps its changed state across ordinary resets and can participate in persistent world-state snapshots. Permanent shortcuts, unlocked doors, permanent world changes.

One Shot — the Actor can be permanently consumed or completed. Unique pickups, one-time chests, permanent interactions.

Those three modes are one axis of FWSRFResetPolicy. Restore strategy and runtime-spawn behaviour are separate axes, so a decision on one never forces a decision on the others.

Reset without reloading the level

A region reset does not reopen the map. Within the requested region, WSRF can:

• restore existing Actors to their captured state;
• respawn placed Actors that were genuinely destroyed, exactly once;
• remove temporary runtime-spawned Actors;
• rebuild parent/child attachments;
• restore versioned custom gameplay state;
• resolve inter-Actor dependencies through Stable IDs;
• process only the requested region, not the whole world.

Features

Region-based world reset

• regions are Gameplay Tags, not a fixed enumeration
• deterministic reset requests with an explicit reason tag
• optional child-region matching through the tag hierarchy
• per-region index, so a reset never scans every Actor in the world
• no permanent Actor Tick architecture
• Game Thread validation: off-thread requests are rejected with an explicit error report
• a reset requested during a reset is queued FIFO, with a 64-operation drain guard against callback loops, and the pure Was WSRF Reset Successful node reads the final queued result correctly

Destroyed Actor restoration

• genuine Destroy() is supported, not simulated by hiding
• exact-once respawn per record
• the Actor returns to its original source Level or container
• the Stable ID is preserved across the respawn
• captured state is restored automatically after the respawn

Automatic state capture

Captured for every managed Actor:

• transform
• Actor tags
• hidden-in-game state
• collision enabled state
• tick state
• attachment metadata: parent, socket, relative transform
• supported Instance Editable properties whose value differs from the class default

Component state is captured through layered capturers covering seven component families: Scene, Primitive, Static Mesh, Skeletal Mesh, Child Actor, Audio, and — through an optional adapter module — Niagara. A Skeletal Mesh Component’s mesh, material overrides and authored animation setup return after a reset; the exact capture and exclusion contract per family is documented in Automatic component capture.

Custom State

• versioned Writer / Reader API: UWSRFStateWriter and UWSRFStateReader
• available from Blueprint and C++ through IWSRFResettable
• named typed values: bool, int64, float, double, enum, name, string, vector, rotator, transform, Gameplay Tag, Gameplay Tag Container, Stable ID
• relationships stored as Stable IDs rather than object pointers
• deterministic restore ordering: parents before children, then reset priority, then Stable ID
• snapshots retain no strong UObject references

Presets

Seven presets configure the component for a common gameplay role in one click:

Preset	Typical use
Enemy	Returns after rest, death or region reset
Boss / Elite	Stays defeated permanently, even after resting
Breakable Prop	May be genuinely destroyed and respawned
Permanent Shortcut	Change survives ordinary resets
Unique Pickup	Consumed once, permanently
Trap	Resettable armed state
Runtime Actor	Temporary spawned Actor, removed on matching reset

Presets exist to remove manual configuration. Every value they set stays editable, and Custom leaves the policy entirely in your hands.

Editor tooling

• editor-native Inspector under Tools → World State Reset Framework
• right-click setup: apply a preset, assign a region, validate or remove WSRF on one or forty level Actors — or an entire Actor Blueprint class — in a single Undo transaction
• Actor Health Check that explains in plain language what will and will not be restored, ending with one corrective action
• Loaded / Destroyed / StreamedOut / Pending Restore visibility
• explicit validation pass with Error / Warning / Info severities
• missing and duplicate Stable ID detection
• configuration warnings: regions, policies, respawnability, attachment cycles, Custom State schema
• filtered Gameplay Tag pickers rooted at the WSRF region and reason tags
• Focus Actor, Copy Stable ID
• Assign Missing IDs, Regenerate Selected ID — transactional, with Undo/Redo
• PIE Reset Region preview with the full reset report
• optional viewport debug visualization

World Partition and streaming

• World Partition, Data Layers, streamed sublevels and Level Instances
• cookable World Manifest built explicitly from the editor
• Pending Restore for Actors that are streamed out
• records for Actors that have never loaded during the current session
• effective identity = Stable ID + container context, so repeated Level Instances stay independent

Persistence adapter

WSRF is a persistence adapter, not a SaveGame system.

Capture WSRF Persistent State -> your SaveGame -> Apply WSRF Persistent State

• only Persistent and One Shot records are exported
• session-only Resettable state is intentionally excluded
• records whose world content is unloaded are deferred, not forced to load
• snapshot and Custom State carry independent schema versions
• older WSRF saves (schema 1 and 2) are migrated automatically to the current schema 3 on import
• optional explicit migration through UWSRFSnapshotMigrator for project-owned legacy formats
• a missing Actor is reported per record and never aborts the whole import

Bonfire & Checkpoint system — included in 1.0

Place any Actor. Right-click → Make Rest Site. Done. The 1.0 release includes a plug-and-play Rest Site layer: one right-click turns your own shrine, bonfire or statue into a working checkpoint — components, persistent identity, respawn and arrival anchors, and an auto-framed thumbnail camera, all in one undoable action. On top of it: discovered/activated states, a drag-reorderable rest action menu with tag conditions, reusable Rest Site Profiles (edit one profile, every linked bonfire follows), a normative rest sequence where project effects run before the save, same-world and cross-world fast travel, player respawn, a replaceable default menu UI, and a versioned multi-world Quick Save that integrates with your existing SaveGame system. No second ID system, no GAS, no CommonUI, no Enhanced Input.

Everything is implemented and validated on UE 5.7 and 5.8 — documented in Bonfire & Checkpoint (Rest Sites); only the updated demo map remains before release.

Blueprint and C++

Normal WSRF usage requires no client C++: the component, the presets, the subsystem, the reset nodes, the Custom State Writer/Reader and both persistence nodes are Blueprint-callable. The Runtime public API remains fully available to C++ projects.

Performance architecture

• no permanent Actor Tick
• indexed Stable-ID lookup
• per-region indexes
• weak Actor references in records
• minimal snapshots
• resets visit targeted records instead of scanning every Actor in the world

Measured numbers, with the machine and build they were taken on, are published in the performance documentation.

Demo content

The plugin ships a playable demonstration map:

/WorldStateResetFramework/Demo/Maps/L_WSRF_Demo

It demonstrates a resettable Goblin enemy next to a Boss that stays permanently defeated after rest, an Orc that can be petrified and returns to life through automatic component capture — skeletal mesh material, Niagara effect and looping audio all restored by the reset — plus a movable prop, a trap, a reset door, genuinely destroyed breakable props, a persistent shortcut, a one-shot pickup, a one-shot chest, a Lever/Door Custom State and Stable-ID relationship, runtime Actor removal, and persistence capture/apply through a small demo SaveGame.

Demo gameplay lives in the removable WorldStateResetFrameworkDemo DeveloperTool module; the Runtime and Editor modules compile without it. Niagara capture ships as a separate optional adapter module, so the core Runtime carries no Niagara dependency.

Requirements

Requirement	Value
Engine	Unreal Engine 5.7 and 5.8
Validated on	UE 5.7.4 and UE 5.8.1
Project type	Blueprint-only or C++
Runtime module dependencies	Core, CoreUObject, Engine, GameplayTags, PhysicsCore
Multiplayer	Not currently validated or supported as a public feature

Full details are in the installation guide.

Scope limitation

It also carries no dependency on Souls Destruction Framework, on Coalborn, or on any purchased content. The Runtime module depends only on the engine modules listed above.