🔎 Object Variables — Technical Deep Dive

Short Description

This document explains the underlying mechanics of the Object Variable system, including registry management, hierarchy resolution, and serialization.

Long Description

Object Variables are the backbone of the Gorgeous Things ecosystem. Unlike standard Unreal variables, they are instanced UObjects that carry their own metadata, replication logic, and command definitions. This architecture allows for dynamic variable creation, nested hierarchies, and universal access through registries without hard-coded references.

🏗️ Architecture Overview

graph TD
    Subsystem[UGorgeousObjectVariableRegistrySubsystem]
    Root[UGorgeousRootObjectVariable]
    Group[UGorgeousObjectVariable]
    Leaf[UGorgeousObjectVariable]
    
    Subsystem -->|Manages| Root
    Root -->|Contains| Group
    Group -->|Contains| Leaf
    
    style Root fill:#0b506e,stroke:#3fb950,stroke-width:2px
    style Subsystem fill:#161b22,stroke:#30363d

🗝️ The Registry System

Path Resolution

Variables are identified by a dot-notated path (e.g., Player.Stats.Health). The UGorgeousObjectVariableRegistrySubsystem resolves these paths by traversing the UGorgeousRootObjectVariable tree.

Registration Lifecycle

  1. Creation: Variables can be created statically via Data Assets or dynamically at runtime.
  2. Registration: Variables register themselves with a parent or the root registry using a unique EntryKey.
  3. Discovery: Other systems can retrieve the variable by path or by searching for specific tags.

📦 Serialization & Persistence

Object Variables support multiple serialization strategies:

  • Binary (FArchive): Used for high-performance network replication.
  • JSON: Used for save-game persistence and external tool integration.
  • Property Copy: Synchronizing values between the UObject instance and external actor properties.

🔗 Variable Inheritance (Class Spaces)

In the Gorgeous Events system, Object Variables support Class Spaces. This allows a child event to "inherit" variable values from its parent if they are not explicitly overridden.

  1. Lookup: When a value is requested, the system first checks the local variable.
  2. Traversal: If not found, it traverses up the ParentEvent chain.
  3. Resolution: The first instance of the variable found in the chain is used.

🛠️ Specialized Containers

Beyond simple values, the system provides specialized variable types:

Type Description
UGorgeousObjectVariable_Queue FIFO buffer for processing sequences
UGorgeousObjectVariable_Stack LIFO storage for state management
UGorgeousObjectVariable_Map Key-value store for dynamic associations
UGorgeousObjectVariable_Counter Thread-safe atomic counter for synchronization