🔁 AutoReplication — Architecture & Flow

Short Description

This document provides a comprehensive technical overview of the AutoReplication system, including the end-to-end replication flow, serialization mechanisms, and component responsibilities.

Long Description

AutoReplication is Gorgeous Core's networking layer for Object Variables. It enables property streaming and RPC-style payloads with client/server routing without requiring manual replication setup. The system uses a mixin-based design that binds to Quality-of-Life classes (Game State, Player Controller, Player State, World Settings) and handles runtime replication through coordinator, relay, and transporter components.

🏗️ System Architecture

graph TB
    subgraph "Client"
        OVC[UGorgeousObjectVariable]
        MixinC[FGorgeousAutoReplicationMixin]
        RelayC[UGorgeousAutoReplicationRPCRelayComponent]
    end
    
    subgraph "Network Layer"
        RPC[Unreal RPC System]
    end
    
    subgraph "Server"
        OVS[UGorgeousObjectVariable]
        MixinS[FGorgeousAutoReplicationMixin]
        TransporterS[UGorgeousAutoReplicationRPCTransporter]
        CoordinatorS[FGorgeousAutoReplicationCoordinator]
    end
    
    OVC --> MixinC
    MixinC --> RelayC
    RelayC -->|Server RPC| RPC
    RPC -->|Server Receive| MixinS
    MixinS --> OVS
    MixinS --> TransporterS
    TransporterS -->|Client/Multicast RPC| RPC
    RPC -->|Client Receive| MixinC
    CoordinatorS --> OVS

🔄 Core Concepts

Payload Types

Type Description
FGorgeousAutoReplicationPropertyValue Serialized bytes for a single registered property, with replication mode + condition
FGorgeousAutoReplicationPropertyPayload A batch of property values for a stream
FGorgeousAutoReplicationPropertyEnvelope Payload + EntryKey used to resolve the target variable on the receiver
FGorgeousQueuedRPC Serialized RPC waiting to be dispatched
FGorgeousRPCPayload Handler name + arguments for RPC invocation

Serialization Modes

Property values are serialized by UGorgeousObjectVariable using one of three strategies:

// EGorgeousReplicationMode::EProperty
// Uses FProperty::SerializeItem for standard property serialization
FProperty->SerializeItem(FStructuredArchiveSlot, PropertyAddress);
// EGorgeousReplicationMode::ENetSerialize
// Calls NetSerialize() if the property type supports it
Value.NetSerialize(Ar, Map, bOutSuccess);
// EGorgeousReplicationMode::EFastArray
// Uses FastArraySerializer for delta-compressed array replication
FastArraySerializer.NetDeltaSerialize(Params);

🛰️ Replication Flow

1. Dirty Tracking (Server)

When a property in an Object Variable is modified, the FGorgeousAutoReplicationMixin identifies the changed bits. If the change meets the EGorgeousReplicationCondition (e.g., OwnerOnly, SkipOwner), it is marked for the next sync.

2. Payload Composition

The FGorgeousAutoReplicationCoordinator gathers all dirty properties from registered mixins. It batches them into a FGorgeousAutoReplicationPropertyPayload.

3. Transmission

  • Server to Client: The UGorgeousAutoReplicationRPCTransporter sends the payload via Multicast or Client RPCs.
  • Client to Server: The UGorgeousAutoReplicationRPCRelayComponent forwards local changes to the server via a Server RPC.

4. Resolution & Application (Receiver)

The receiver uses the EntryKey inside the FGorgeousAutoReplicationPropertyEnvelope to find the local instance of the Object Variable. The serialized bytes are then unpacked directly into the variable's memory using the appropriate serialization mode.

⚡ Performance Optimization

  • Dirty-Bit Masking: Only changed properties are serialized and sent.
  • Replication Conditions: Properties can be restricted to specific connection types to save bandwidth.
  • Shared Serialization: Payloads are serialized once and multi-cast to all relevant clients.
  • Iris Integration: Supports the Iris Replication System for high-density actor counts.