Regions and reset requests

Regions are Gameplay Tags

A region is a Gameplay Tag assigned to a state component or to a registration request. An Actor can belong to several regions at once.

Tags rather than an enumeration means your project defines its own vocabulary — WSRF.Region.Dungeon, WSRF.Region.Boss.Arena — without editing the plugin. The subsystem keeps a per-region index of Stable IDs, so Reset World Region visits only the records in that region instead of scanning the world.

The tags shipped by the plugin:

Tag	Purpose
WSRF.Region.Default	A usable region out of the box
WSRF.Region.DemoHall	Used by the demo map
WSRF.Region.Test.A, .B, .Stress	Used by the automation tests

Create project tags as children of WSRF.Region — the editor picker is filtered to that root, and the reason picker is similarly filtered to WSRF.Reset. The filter guides new data; it does not invalidate or erase existing serialized tags outside those roots.

Child regions

bIncludeChildRegions (default true) matches through the tag hierarchy: resetting WSRF.Region.Dungeon also resets WSRF.Region.Dungeon.Cellar. Set it to false to touch exactly one level of the hierarchy.

Changing regions at runtime

Set Region Membership updates the active subsystem record immediately. Use it only for deliberate runtime ownership changes — for authored setup, prefer the component Details panel or Assign Region in the WSRF context menu. On a World Partition map, rebuild and save the World Manifest after ID or region changes — see World Partition and World Manifest.

Reset reasons

The reason is also a Gameplay Tag. A record only responds when the request’s reason is present in its policy’s ResetTriggers.

Tag	Typical meaning
WSRF.Reset.Rest	The player rested at a checkpoint
WSRF.Reset.PlayerDeath	The player died
WSRF.Reset.Checkpoint	A checkpoint was reached or reloaded
WSRF.Reset.Region	A region-scoped reset
WSRF.Reset.EncounterRestart	An encounter restarted
WSRF.Reset.Manual	An explicit manual or debug reset

This is what lets one world hold Actors that react differently to the same event: an enemy returns on Rest, a puzzle only resets on EncounterRestart, and a shortcut ignores both.

The request

FWSRFResetRequest:

Field	Type	Default	Meaning
Reason	FGameplayTag	none	Why the reset is happening
Region	FGameplayTag	none	Which region to reset
Initiator	UObject*	nullptr	Whatever caused it; carried through to listeners
Context	FName	NAME_None	Free-form label for your own diagnostics
bIncludeChildRegions	bool	true	Match child region tags
ContainerContext	FGuid	invalid	Advanced. Restrict to one Level Instance container

ResetWorldRegion(Region, Reason, Initiator, bIncludeChildRegions) is the convenience entry point that builds this struct for you. RequestReset(Request) takes the full struct when you need Context or ContainerContext.

The report

Both calls return FWSRFResetReport synchronously:

Field	Meaning
OperationId	A GUID identifying this reset operation
Scheduled	Records selected by the request
Restored	Existing Actors returned to their captured state
Respawned	Destroyed placed Actors recreated
Removed	Runtime-spawned Actors removed
Skipped	Records intentionally not processed
PendingRestore	Records whose Actor is not currently loaded
Failed	Records that could not be processed
DurationMilliseconds	Wall-clock duration of the operation
Errors	One message per failure

WasSuccessful() is true when Failed is zero. A single invalid Actor never stops the rest of the region: it increments Failed, adds an error string, and the pipeline continues.

PendingRestore above zero is normal on a streamed map — those Actors are not loaded right now and will be reconciled when their container returns. See World Partition and World Manifest.

Reset pipeline order

Prepare and notify
    ↓
Remove matching runtime Actors
    ↓
Respawn missing placed Actors
    ↓
Restore automatic state
    ↓
Restore parent/child attachments
    ↓
Restore custom state
    ↓
Notify and report

Ordering inside each phase is deterministic: parents before attached children, then ascending ResetPriority, then Stable ID. Two runs over the same world produce the same order.

Because respawn happens before custom restore, a Custom State callback can safely resolve a Stable ID for an Actor that was destroyed before the reset started — by then it exists again.

Nested resets

A reset requested from inside a callback — an OnWorldResetCompleted handler, a WSRF Reset Completed event — is queued FIFO and starts only after the active reset has fully finished. There is no re-entrancy and no partially applied pipeline.

The immediate return of a queued request is a placeholder report: bWasQueued true, bWasExecuted false. Its OperationId is retained by the eventual completed report — match it in the completion delegates and judge that final report with the pure Was WSRF Reset Successful node, which is true only when bWasExecuted is true and Failed is zero.

One queue drain executes at most 64 queued resets. If callbacks keep generating requests, the remaining entries receive completion reports with bWasQueued true, bWasExecuted false, Failed = 1 and an explanatory error — a safety guard so a Blueprint callback loop cannot block the Game Thread indefinitely. Avoid requesting a reset unconditionally from a reset-completed event.

Reset requests are Game Thread only; an off-thread call is rejected with an explicit error report.

GetResetOperationState reports where the subsystem currently is: Idle, Preparing, RemovingRuntimeActors, RespawningMissingActors, RestoringAutomaticState, RestoringAttachments, RestoringCustomState or Finalizing.

Events

On UWSRFWorldStateSubsystem:

Delegate	Parameters	Fires
OnWorldResetStarted	FWSRFResetRequest	A reset begins
OnWorldResetCompleted	FWSRFResetRequest, FWSRFResetReport	A reset finishes
OnRegionResetStarted	FWSRFResetRequest	A region-scoped reset begins
OnRegionResetCompleted	FWSRFResetRequest, FWSRFResetReport	A region-scoped reset finishes
OnActorResetStarted	FWSRFActorId, FWSRFResetRequest	One Actor starts being processed
OnActorResetCompleted	FWSRFActorId, FWSRFResetRequest	One Actor is done

Per-Actor callbacks are also available locally on the state component and through IWSRFResettable, which is usually the better place for gameplay logic.

Resetting inside a Level Instance

ResetWorldRegionInContext(Region, Reason, ContextActor, Initiator, bIncludeChildRegions) limits the reset to the container that owns ContextActor. Two copies of the same Level Instance therefore reset independently. Normal maps should keep using Reset World Region.