UE5 Iris Replication System 완전 가이드

개요

Iris는 UE5.1에서 도입된 차세대 네트워크 레플리케이션 시스템입니다. 기존 Actor 기반 레플리케이션의 한계를 극복하고 대규모 멀티플레이어 게임에 필요한 확장성, 필터링, 우선순위 처리를 개선합니다.

활성화: Project Settings → Network → Use Iris Replication System

---

1. 기존 레플리케이션 vs Iris

항목	기존 레플리케이션	Iris
아키텍처	Actor 중심	데이터 중심
필터링	NetCullDistanceSqrd	유연한 필터 시스템
우선순위	거리 기반 단순	세분화된 우선순위
성능	단일 스레드	멀티스레드 지원
디버깅	제한적	전용 Iris Inspector

---

2. ReplicationFragment

Iris의 핵심 개념으로, 레플리케이션할 데이터를 Fragment로 분리합니다.

#include "Iris/ReplicationSystem/ReplicationFragment.h"
#include "Iris/ReplicationState/ReplicationStateDescriptorBuilder.h"

// 레플리케이션 상태 정의
USTRUCT()
struct FPlayerStateData
{
    GENERATED_BODY()

    UPROPERTY()
    float Health = 100.f;

    UPROPERTY()
    int32 Score = 0;

    UPROPERTY()
    FVector_NetQuantize Location;
};

// Actor에서 Iris 레플리케이션 설정
UCLASS()
class AMyPlayerState : public APlayerState
{
    GENERATED_BODY()

public:
    // Iris 레플리케이션 Fragment 등록
    virtual void RegisterReplicationFragments(
        UE::Net::FFragmentRegistrationContext& Context,
        UE::Net::EFragmentRegistrationFlags RegistrationFlags) override;

private:
    UPROPERTY(Replicated)
    FPlayerStateData ReplicatedData;
};

---

3. NetHandle — 엔티티 식별자

#include "Iris/ReplicationSystem/NetHandle.h"
#include "Iris/ReplicationSystem/ReplicationSystem.h"

void ManageNetHandles()
{
    UReplicationSystem* RepSystem =
        GetWorld()->GetSubsystem<UNetworkSubsystem>()
            ->GetReplicationSystem(0);

    if (!RepSystem) return;

    // Actor의 NetHandle 조회
    UE::Net::FNetHandle Handle =
        UE::Net::FReplicationSystemUtil::GetNetHandle(MyActor);

    if (Handle.IsValid())
    {
        // 레플리케이션 상태 강제 더티 표시
        RepSystem->MarkNetObjectStateDirty(Handle);
    }
}

---

4. 필터링 시스템

#include "Iris/ReplicationSystem/Filtering/NetObjectFilter.h"

// 커스텀 필터 구현
UCLASS()
class UTeamFilter : public UNetObjectFilter
{
    GENERATED_BODY()

public:
    virtual void Filter(
        FNetObjectFilteringParams& Params) override
    {
        // 팀이 같은 플레이어에게만 레플리케이션
        for (uint32 ObjectIndex : Params.ObjectIndices)
        {
            const FTeamData* TeamData = GetTeamData(ObjectIndex);
            const FTeamData* ViewerTeamData = GetViewerTeamData(Params.View);

            bool bSameTeam = TeamData && ViewerTeamData
                && TeamData->TeamId == ViewerTeamData->TeamId;

            Params.OutAllowedObjects.SetBitValue(ObjectIndex, bSameTeam);
        }
    }
};

---

5. 우선순위 시스템

#include "Iris/ReplicationSystem/Prioritization/NetObjectPrioritizer.h"

UCLASS()
class UGameplayPrioritizer : public UNetObjectPrioritizer
{
    GENERATED_BODY()

public:
    virtual void Prioritize(
        FNetObjectPrioritizerParams& Params) override
    {
        for (uint32 ObjectIndex : Params.ObjectIndices)
        {
            float Priority = 1.0f;

            // 플레이어 근처 오브젝트 우선순위 증가
            float Distance = GetDistanceToViewer(ObjectIndex, Params.View);
            Priority = FMath::Max(0.1f, 1.0f - Distance / 5000.f);

            // 전투 중인 액터 우선순위 증가
            if (IsInCombat(ObjectIndex))
                Priority *= 2.0f;

            Params.Priorities[ObjectIndex] = Priority;
        }
    }
};

---

6. 레플리케이션 조건 설정

// 기존 레플리케이션 조건과 Iris 매핑
// COND_OwnerOnly → 소유자에게만 전송

UCLASS()
class AMyCharacter : public ACharacter
{
    GENERATED_BODY()

    // 기존 방식 (Iris에서도 지원)
    UPROPERTY(ReplicatedUsing = OnRep_Health)
    float Health = 100.f;

    UPROPERTY(Replicated, ReplicationCondition = COND_OwnerOnly)
    float Stamina = 100.f;

    virtual void GetLifetimeReplicatedProps(
        TArray<FLifetimeProperty>& OutLifetimeProps) const override
    {
        Super::GetLifetimeReplicatedProps(OutLifetimeProps);
        DOREPLIFETIME(AMyCharacter, Health);
        DOREPLIFETIME_CONDITION(AMyCharacter, Stamina, COND_OwnerOnly);
    }
};

---

7. Iris Inspector 디버깅

콘솔 명령:
  net.Iris.Inspector 1          - Iris 인스펙터 활성화
  net.Iris.DebugFilter [클래스명] - 특정 클래스 필터 디버그
  net.Iris.Stats                 - 레플리케이션 통계 출력
  net.Iris.DumpObjects           - 레플리케이션 객체 목록

---

8. 마이그레이션 전략

// 기존 코드 유지 + Iris 점진적 도입

// 1단계: Iris 활성화 (기존 코드 그대로 작동)
// ProjectSettings → Network → Use Iris Replication System

// 2단계: 성능 병목 확인 후 Fragment로 최적화
// net.Iris.Stats로 대역폭 분석

// 3단계: 커스텀 필터/우선순위 적용
// 불필요한 레플리케이션 제거

// 기존 레플리케이션 호환성 체크
void ValidateIrisCompatibility()
{
    // Iris는 대부분의 기존 UPROPERTY(Replicated) 자동 지원
    // 예외: 일부 복잡한 커스텀 레플리케이션 로직
}

---

정리

• Iris = 데이터 중심 레플리케이션 (기존 Actor 중심 대체)
• ReplicationFragment — 레플리케이션 데이터 단위
• NetHandle — 네트워크 엔티티 식별자
• 필터 시스템 — 팀/지역/권한 기반 세분화 필터링
• 우선순위 시스템 — 거리/전투 상태별 대역폭 최적화
• 기존 UPROPERTY(Replicated) 코드 대부분 호환

참고 자료

• UE Docs — Iris Replication System