Level Instances, Data Layers and sublevels

Level Instances create a problem that Stable IDs alone cannot solve: place the same source level three times and you have three Actors carrying the same authored ID. WSRF handles it with container identity, and the whole mechanism is automatic.

Container identity

Every managed Actor resolves to a FWSRFContainerIdentity:

Field	Meaning
ContextGuid	Invalid for the main world; a deterministic GUID for a streamed container
SourceLevelPackage	The authored level the Actor belongs to
RuntimeLevelPackage	The level package it lives in at runtime
ContainerLabel	A readable label for diagnostics
DataLayers	The Data Layer names that apply to it

Combined with the local Stable ID, that produces the effective identity used by records, the World Manifest and persistence snapshots.

Repeated Level Instances

Two copies of the same source level get different container GUIDs, so their Actors get different effective identities even though their local Stable IDs are identical.

Consequences, all of them automatic:

• resetting one instance does not touch the other;
• persistent state saved for one instance applies only to that instance;
• a Stable-ID dependency resolves inside its own instance when you use the context-aware lookup.

Level Instance A: local id 7f3c… + container GUID A  ->  effective identity A
Level Instance B: local id 7f3c… + container GUID B  ->  effective identity B

Context-aware nodes

When content is instanced, “find the lever with this ID” is ambiguous. These nodes disambiguate by container:

Node	Use
Find Loaded Actor In Context	Resolve a local Stable ID inside the caller’s own container. Pass any Actor from that container as context.
Find Loaded Actor By Effective Id	Resolve a full effective identity directly
Reset World Region In Context	Reset a region only inside the container owning the context Actor
FWSRFResetRequest::ContainerContext	The same restriction expressed on a full request

Inside instanced content, prefer Find Loaded Actor In Context over Find Loaded Actor. In a normal non-instanced map the two behave the same.

Data Layers

Data Layer names are part of the container identity, so records carry the Data Layers that applied to their Actor.

A reset targeting Actors in an inactive Runtime Data Layer does not activate it. Those records are marked Pending Restore and reconciled when the layer becomes active and the Actors register again — the same rule as unloaded World Partition cells.

Streamed sublevels

Independently streamed sublevels behave like any other container: their Actors resolve a container identity from their level package, unloading marks records StreamedOut rather than Destroyed, and reloading rebinds each Actor to its existing record.

The subsystem listens for level add and remove events, so a sublevel returning triggers reconciliation of its pending records without any call from your code.

Reset semantics across containers

Situation	Result
Region reset, all content loaded	Applied immediately
Region reset, some cells unloaded	Loaded records applied, unloaded ones marked Pending Restore
Region reset with ContainerContext set	Only records in that container are selected
Sublevel reloads after a pending reset	The pending reset is applied on registration
A Level Instance is unloaded and reloaded	Records rebind by effective identity; no duplicates

Verified scope

The streaming behaviour documented here corresponds to what was validated during development: repeated Level Instances, independent sublevels and Runtime Data Layers, ten-cycle non-duplication gates, and a 10,000-record manifest benchmark.

Related

• World Partition and World Manifest
• Persistence adapter — deferred restore for unloaded records
• Troubleshooting