🛠️ Specialized Variables & Roots

Short Description

This document covers the specialized container variables (Queues, Stacks, Maps) and the Root Registry management system.

Long Description

Beyond simple single-value variables, Gorgeous Core provides a suite of specialized UGorgeousObjectVariable subclasses that behave like standard Unreal containers (TArray, TMap, TSet) but with all the benefits of the Object Variable system (replication, persistence, and hierarchy). This document also details the UGorgeousRootObjectVariable, which serves as the entry point for all variable resolution and ownership management.

🗃️ Root Registry

The UGorgeousRootObjectVariable is a singleton-like container that anchors the variable tree. You can have multiple named roots for different domains (e.g., "World", "SaveData", "Networking").

`GetRootObjectVariable`

Retrieves or lazily creates a named root object variable.

Parameter Name	Type	Description
`RootName`	`FName`	The name of the root registry to retrieve. If None, returns the default root.

`FindVariableByIdentifier`

Performs a fast global lookup for a variable using its unique GUID.

Parameter Name	Type	Description
`Identifier`	`FGuid`	The unique identifier to search for.

`ClaimRootRegistryOwnership`

Claims authoritative ownership of a root registry. Essential for ensuring stable replication contexts in multiplayer.

Parameter Name	Type	Description
`RootName`	`FName`	The root to claim.
`StableIdentifier`	`FString`	A persistent string identifying the owner (e.g., Connection ID).
`OwningContext`	`UObject*`	The context object (PlayerController, etc.) that will own the registry.

📐 Specialized Containers

The system includes pre-defined classes for common data structures. Each supports standard operations via Blueprint-callable thunks.

Queue & Stack Variables

Manage ordered collections of variables. Supports Enqueue, Dequeue, Push, and Pop operations.

Map & MultiMap Variables

Store variables keyed by FName or FString. MultiMaps allow multiple values per key.

Set Variables

Ensure a collection of unique variables with fast membership testing.

📚 Usage Examples

// Accessing a queue variable
UQueue_SOV* MyQueue = Root->FindInRegistry<UQueue_SOV>("ActionQueue");
MyQueue->Enqueue(SomeVariable);

Use Get Universal Variable or Set Universal Variable with a FGuid to interact with any registered variable regardless of its position in the hierarchy.

Best Practices

Root Separation: Use different roots for data that has different lifecycles (e.g., "Session" for transient data vs. "Save" for persistent data).
Ownership: Always call ReleaseRootRegistryOwnership when an owner (like a player) disconnects to prevent memory leaks and stale authority.
Specialized Overrides: If you need custom logic for a container (e.g., a "Sorting Inventory"), inherit from UArray_SOV and override its methods.

Troubleshooting

Root Null: Ensure you are requesting a root name that is either None (default) or registered in the Gorgeous Root Object Variable Settings.
Orphaned Variables: If a root is destroyed, use SetDefaultOrphanResolution to determine if children should be destroyed or reparented to another root.
Conflict in Ownership: Only one context can "Claim" a root at a time. Restoration handles returning owners after a disconnect.