Unreal Engine replicated USTRUCT 배열 assertion을 정확히 고치기

문제가 된 구조체#

문제가 된 구조체는 아래 형태였다.

1
USTRUCT()
2
struct FMagazine_NetQuantize
3
{
4
    GENERATED_BODY()
5

6
    FGuid MagazineId;
7
    int32 AmmoId = INDEX_NONE;
8
    int32 AmmoAmount = 0;
9
};

GENERATED_BODY()가 있으므로 FMagazine_NetQuantize라는 script struct 타입 자체는 Unreal reflection system에 등록된다. 하지만 세 멤버는 일반 C++ 필드일 뿐 FProperty로 등록되지 않는다. reflection이 보는 내부 구조는 비어 있다.

이 타입이 다음처럼 Actor의 replicated array에 들어갔다고 가정해 보자.

1
UPROPERTY(Replicated)
2
TArray<FMagazine_NetQuantize> Magazines;

replication은 배열 값과 shadow state를 비교하면서 내부 reflected property를 따라 change handle을 만든다. 실제 배열이 shadow보다 커졌는데 원소 내부에서 만들 수 있는 handle이 하나도 없으면, 배열 command가 기대한 형태와 맞지 않아 위 assertion에 도달할 수 있다.

원인은 C++ 구조체의 byte 수가 0이어서가 아니다. C++에는 세 필드가 있지만 기본 복제 스키마가 보는 필드 수가 0개라는 불일치가 핵심이다.

최소 재현: 구조체 하나에서도 같은 계약#

같은 문제는 이름이나 실제 데이터 종류와 무관하게 더 작은 구조체에서도 만들 수 있다.

1
USTRUCT()
2
struct FReplicatedPayload
3
{
4
    GENERATED_BODY()
5

6
    TArray<uint8> Data;
7
};
8

9
UCLASS()
10
class APayloadOwner : public AActor
11
{
12
    GENERATED_BODY()
13

14
    UPROPERTY(Replicated)
15
    FReplicatedPayload Payload;
16
};

바깥 Payload property가 replicated라고 해도 내부 Data는 reflection에 등록되지 않는다. Actor가 구조체를 전송 대상으로 등록하는 것과 구조체가 전송할 내부 field를 제공하는 것은 서로 다른 계약이다. 기본 serializer를 사용한다면 내부 선언도 다음처럼 반사해야 한다.

1
USTRUCT()
2
struct FReplicatedPayload
3
{
4
    GENERATED_BODY()
5

6
    UPROPERTY()
7
    TArray<uint8> Data;
8
};

이 최소 사례는 배열 assertion이 아니더라도 “바깥 property에 Replicated를 붙였으니 구조체 내부 일반 C++ field도 자동 전송된다”는 오해를 판별하는 데 유용하다. 실제 오류가 TArray<FReplicatedPayload>에서 발생했다면 아래의 동적 배열 진단과 함께 적용한다.

기본 reflection 복제에 맞는 수정#

클라이언트로 보내야 하는 필드를 모두 반사하고 Actor의 바깥 property를 replicated property로 등록한다.

1
#pragma once
2

3
#include "CoreMinimal.h"
4
#include "MagazineNetQuantize.generated.h"
5

6
USTRUCT(BlueprintType)
7
struct FMagazine_NetQuantize
8
{
9
    GENERATED_BODY()
10

11
    UPROPERTY()
12
    FGuid MagazineId;
13

14
    UPROPERTY()
15
    int32 AmmoId = INDEX_NONE;
16

17
    UPROPERTY()
18
    int32 AmmoAmount = 0;
19
};

구조체 내부 필드에는 다시 Replicated를 붙이지 않는다. Actor의 Magazines가 replication 단위이며 기본 struct serializer가 그 안의 reflected field를 순회하기 때문이다.

1
#pragma once
2

3
#include "CoreMinimal.h"
4
#include "GameFramework/Actor.h"
5
#include "MagazineNetQuantize.h"
6
#include "MagazineOwner.generated.h"
7

8
UCLASS()
9
class YOURGAME_API AMagazineOwner : public AActor
10
{
11
    GENERATED_BODY()
12

13
public:
14
    AMagazineOwner();
15

16
    virtual void GetLifetimeReplicatedProps(
17
        TArray<FLifetimeProperty>& OutLifetimeProps) const override;
18

19
protected:
20
    UPROPERTY(ReplicatedUsing = OnRep_Magazines)
21
    TArray<FMagazine_NetQuantize> Magazines;
22

23
    UFUNCTION()
24
    void OnRep_Magazines();
25
};

1
#include "MagazineOwner.h"
2
#include "Net/UnrealNetwork.h"
3

4
AMagazineOwner::AMagazineOwner()
5
{
6
    bReplicates = true;
7
}
8

9
void AMagazineOwner::GetLifetimeReplicatedProps(
10
    TArray<FLifetimeProperty>& OutLifetimeProps) const
11
{
12
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);
13
    DOREPLIFETIME(AMagazineOwner, Magazines);
14
}
15

16
void AMagazineOwner::OnRep_Magazines()
17
{
18
    // 클라이언트 표시나 조회 캐시를 새 최종 상태로 갱신한다.
19
}

이 구성은 네 층의 계약을 모두 갖춰야 한다.

1. AMagazineOwner가 실제로 복제되도록 bReplicates = true다.
2. 바깥 property에 Replicated 또는 ReplicatedUsing이 있다.
3. GetLifetimeReplicatedProps가 Super를 호출하고 DOREPLIFETIME으로 property를 등록한다.
4. 기본 serializer로 보낼 struct field에 UPROPERTY()가 있다.

하나라도 빠지면 assertion이 사라졌더라도 원하는 데이터가 전송된다는 보장은 없다.

“모든 멤버”가 아니라 “보낼 멤버”#

구조체 안에는 서버나 클라이언트가 로컬로만 계산하는 캐시가 있기도 한다. 그 값은 복제 스키마에서 명시적으로 제외하면 된다.

1
USTRUCT(BlueprintType)
2
struct FMagazine_NetQuantize
3
{
4
    GENERATED_BODY()
5

6
    UPROPERTY()
7
    FGuid MagazineId;
8

9
    UPROPERTY()
10
    int32 AmmoId = INDEX_NONE;
11

12
    UPROPERTY()
13
    int32 AmmoAmount = 0;
14

15
    UPROPERTY(NotReplicated, Transient)
16
    int32 LocalDisplaySortKey = 0;
17
};

Unreal Engine property 문서는 NotReplicated가 struct member의 기본 복제를 건너뛰는 specifier라고 설명한다. 이렇게 선언하면 필드는 reflection, editor tooling, 복사나 다른 serialization에 남겨 두되 네트워크 스키마에서는 제외한다는 의도가 분명해진다. Transient는 일반 asset/save serialization에서도 유지하지 않겠다는 별도 선택이다.

평범한 non-UPROPERTY C++ 필드를 로컬 캐시로 두는 방법도 있다. 다만 아래 차이는 감수해야 한다.

• reflection 기반 복제, 저장, editor 노출과 property 비교가 그 필드를 보지 못한다.
• reflection이 수행하는 struct 복사나 초기화 경로에서 기대한 의미가 유지되는지 별도로 검증해야 한다.
• UObject 참조를 추적해야 하는 필드를 무심코 non-UPROPERTY로 두면 garbage collection과 수명 관리가 깨질 위험이 있다.
• 복제 상태와 로컬 캐시가 함께 복사되거나 reset되는 시점을 코드가 직접 책임져야 한다.

따라서 단순 POD 파생 캐시가 아니라 엔진 수명과 serialization에 참여해야 하는 값이라면 UPROPERTY(NotReplicated)로 의도를 표현하는 편이 안전하다.

custom NetSerialize는 별도의 예외다#

기본 reflected serializer 대신 구조체가 직접 bitstream을 정의할 수도 있다.

1
bool NetSerialize(FArchive& Ar, UPackageMap* Map, bool& bOutSuccess);
2

3
template <>
4
struct TStructOpsTypeTraits<FCompressedMagazineSnapshot>
5
    : public TStructOpsTypeTraitsBase2<FCompressedMagazineSnapshot>
6
{
7
    enum
8
    {
9
        WithNetSerializer = true,
10
    };
11
};

WithNetSerializer = true가 올바르게 등록되면 FStructProperty::NetSerializeItem은 해당 native 함수를 호출한다. 이 경우 함수가 일반 C++ field를 직접 encoding하므로 “모든 field는 UPROPERTY여야 한다”는 기본 serializer 규칙의 예외가 된다.

그러나 WithNetSerializer는 전송 형식만 바꾼다. non-UPROPERTY 상태의 변경 감지까지 자동으로 해결하지는 않는다. 기본 UScriptStruct 비교는 reflected property를 사용하므로 custom payload만 바뀌었을 때 새 값이 dirty로 잡히지 않는 경우가 있다. 이런 상태를 직접 직렬화한다면 정확한 operator==와 WithIdenticalViaEquality, 또는 Identical 구현과 WithIdentical trait까지 함께 설계해야 한다. 배열에 첫 원소를 추가할 때는 전송되지만 기존 원소의 native field만 바꾸면 누락되는 식의 교묘한 버그가 생기기도 한다.

custom serializer를 선택하면 더 큰 책임이 따른다.

• 송신과 수신은 정확히 같은 field 순서와 bit 수를 사용해야 한다.
• enum, index, count, string 길이와 정수 범위는 역직렬화 전에 제한한다.
• UObject 참조는 raw address가 아니라 UPackageMap을 통한 network reference로 처리해야 한다.
• 이전 클라이언트와 protocol version 호환성을 설계해 둔다.
• equality/change detection과 실패 시 bOutSuccess 의미를 검증해 둔다.

구조체 이름에 _NetQuantize를 붙이는 것만으로 quantization이나 NetSerialize가 생기지 않는다. 엔진의 FVector_NetQuantize 같은 타입은 이름 때문이 아니라 실제 serializer와 traits가 구현되어 있어 동작한다.

assertion을 만났을 때의 진단 순서#

빠른 판별표#

핵심은 단순히 macro를 더 붙이는 데 있지 않다. C++ memory layout, Unreal reflection layout, network serialization layout은 서로 다르다. 기본 복제를 사용할 때는 바깥 property와 전송할 내부 field를 모두 reflection에 명시하고, 제외할 field는 의도적으로 표시한다. custom serializer를 선택한 순간부터는 wire format과 변경 감지를 직접 책임져야 한다.

참고 자료#

• Epic Games: Replicate Actor Properties
• Epic Games: Unreal Engine UProperties
• Epic Games: UScriptStruct::ICppStructOps::NetSerialize