UE5 Iris 복제 시스템 완전 가이드

개요

Iris는 UE 5.1에서 도입된 차세대 네트워크 복제 시스템으로, 기존 액터 기반 복제의 성능 한계를 극복하기 위해 설계되었습니다. 데이터 중심 아키텍처로 대규모 멀티플레이어(수백~수천 플레이어)에서 CPU 효율과 대역폭 효율을 크게 개선합니다.

---

1. Iris 활성화

; DefaultEngine.ini
[/Script/Engine.NetworkSettings]
bIrisEnabled=True

; 또는 커맨드라인
-IrisEnabled=1

// 프로젝트 설정에서 확인
// Edit > Project Settings > Engine > Network > Iris Replication System

---

2. 기존 복제 vs Iris

기존 복제 (Legacy):
- 액터 단위 복제 체크
- 매 틱마다 더티 체크 (O(n))
- 싱글 스레드

Iris:
- ReplicationFragment 단위 (데이터 중심)
- 변경된 데이터만 선택적 복제
- 멀티스레드 패킷 직렬화
- NetHandle로 오브젝트 참조
- FilterProfile로 관련성 필터링

---

3. ReplicationFragment — 복제 단위

// Iris 복제를 위한 Fragment 정의
#include "Iris/ReplicationSystem/ReplicationFragment.h"

// 복제할 상태 구조체
USTRUCT()
struct FPlayerStateFragment
{
    GENERATED_BODY()

    UPROPERTY()
    float Health = 100.f;

    UPROPERTY()
    int32 Score = 0;

    UPROPERTY()
    FVector Position;
};

// Fragment 등록 (cpp)
void AMyPlayerState::RegisterReplicationFragments(
    UE::Net::FFragmentRegistrationContext& Context,
    UE::Net::EFragmentRegistrationFlags Flags)
{
    Super::RegisterReplicationFragments(Context, Flags);

    // 구조체 복제 등록
    ReplicationFragments::CreateAndRegisterFragmentForObject<
        FPlayerStateFragment>(this, Context, Flags);
}

---

4. NetHandle — 복제 오브젝트 참조

#include "Iris/ReplicationSystem/NetHandle.h"

// NetHandle을 통한 오브젝트 참조
UReplicationSystem* RepSystem =
    UReplicationSubsystem::GetReplicationSystem(GetWorld());

if (RepSystem)
{
    // 액터의 NetHandle 획득
    UE::Net::FNetHandle Handle =
        RepSystem->GetReplicationWriter()->GetNetHandleFromObject(
            TargetActor);

    if (Handle.IsValid())
    {
        // 해당 핸들의 복제 우선순위 변경
        RepSystem->SetReplicationPriority(Handle, 10.f);
    }
}

---

5. FilterProfile — 관련성 필터링

// 플레이어별 관련성 필터 설정
#include "Iris/ReplicationSystem/NetObjectFilterDefinitions.h"

// 커넥션별 필터 프로파일
void AMyGameMode::SetupConnectionFilters(
    UReplicationSystem* RepSystem)
{
    // 팀 기반 필터: 같은 팀만 상세 정보 복제
    for (auto& [PlayerId, Connection] : ActiveConnections)
    {
        UE::Net::FNetObjectFilteringParams Params;
        Params.ConnectionHandle = Connection.Handle;

        // 팀 필터 적용
        RepSystem->SetConnectionFilter(
            Connection.Handle,
            TeamFilterId,
            Params);
    }
}

// 커스텀 필터 구현
class FTeamNetObjectFilter : public FNetObjectFilter
{
public:
    virtual ENetFilterStatus Filter(
        const FNetObjectFilteringParams& Params) override
    {
        // 같은 팀이면 복제 허용
        if (IsSameTeam(Params.ConnectionId, Params.ObjectId))
            return ENetFilterStatus::Allow;

        // 다른 팀은 위치만 복제 (저해상도)
        return ENetFilterStatus::AllowWithReducedDetail;
    }
};

---

6. 복제 우선순위와 조건

// Iris의 복제 조건 시스템
UCLASS()
class AMyActor : public AActor
{
    GENERATED_BODY()

public:
    // 복제 조건 설정
    virtual void GetReplicationList(
        TArray<FLifetimeProperty>& OutLifetimeProps) const override
    {
        Super::GetReplicationList(OutLifetimeProps);

        // 소유자에게만
        DOREPLIFETIME_CONDITION(AMyActor, PrivateData,
            COND_OwnerOnly);

        // 초기 전송 후 조건부
        DOREPLIFETIME_CONDITION(AMyActor, InitialSetup,
            COND_InitialOnly);

        // 커스텀 조건
        DOREPLIFETIME_CONDITION(AMyActor, TeamData,
            COND_Custom);
    }
};

---

7. 마이그레이션 전략

// 기존 코드와 공존 — 점진적 마이그레이션
// 1단계: Iris 활성화 (기존 코드 그대로 동작)
// 2단계: 성능 임계 액터부터 Fragment로 전환
// 3단계: 커스텀 필터 적용

// 기존 UPROPERTY(Replicated) 호환 확인
// Iris는 기존 GetLifetimeReplicatedProps를 자동으로 읽음
// 대부분의 경우 코드 변경 없이 Iris로 전환 가능

// 성능 프로파일링
void CheckIrisPerformance()
{
    // 통계 출력
    // stat IrisReplication
    // stat NetReplication
}

---

정리

Iris는 UE 5.1+ 대규모 멀티플레이어 프로젝트의 필수 검토 사항입니다. 기존 복제 코드와 대부분 호환되므로 bIrisEnabled=True 활성화부터 시작해 stat IrisReplication으로 성능을 측정하세요. 대역폭과 CPU 병목이 심한 액터부터 ReplicationFragment로 전환하고, FilterProfile로 불필요한 데이터가 전송되지 않도록 관련성을 정교하게 제어하세요.