Unreal Engine 네트워크 코드의 두 가지 함정: 컨테이너 복제와 Deferred Spawn

1. TMap과 TSet은 무엇이 지원되지 않는가#

정확히 말하면 이렇다.

일반 UPROPERTY(Replicated) 또는 ReplicatedUsing으로 선언한 TMap·TSet, 그리고 일반 RPC의 Map/Set 인자는 지원되지 않는다. 이것은 컨테이너의 데이터를 네트워크로 표현할 방법이 전혀 없다는 뜻은 아니다.

UnrealHeaderTool은 복제 프로퍼티와 RPC에서 Map/Set을 거부한다. 런타임의 FMapProperty::NetSerializeItem과 FSetProperty::NetSerializeItem도 이름만 보고 지원한다고 판단해서는 안 된다. 해당 구현은 지원하지 않는다는 오류를 기록한다. Blueprint Map/Set 변수도 예외가 아니다.

Epic의 UE-137102 이슈는 이를 우회하려면 컨테이너를 USTRUCT로 감싸고 사용자 정의 NetSerialize를 구현해야 한다고 설명한다. 그러나 이것은 고급 사용자 정의 프로토콜이며, 아래처럼 평범한 선언이 자동으로 동작한다는 뜻이 아니다.

1
// 일반 property replication에서는 지원되지 않는다.
2
UPROPERTY(Replicated)
3
TMap<FName, int32> ScoreByPlayer;
4

5
UPROPERTY(Replicated)
6
TSet<FName> ReadyPlayers;

반대로 TArray와 Fast Array는 복제할 수 있다. 가장 단순한 기본 해법은 네트워크 표현과 런타임 조회 표현을 분리하는 것이다.

작은 상태: TArray<FEntry>를 복제하고 OnRep에서 재구성하기#

점수표처럼 항목 수가 작고 변경 빈도가 낮다면 키와 값을 가진 구조체 배열을 복제한다. 서버는 배열을 정본으로 관리하고, 서버와 각 클라이언트는 빠른 조회를 위한 TMap 캐시를 로컬에서 만든다.

1
#pragma once
2

3
#include "CoreMinimal.h"
4
#include "GameFramework/Actor.h"
5
#include "ReplicatedScoreboard.generated.h"
6

7
USTRUCT(BlueprintType)
8
struct FReplicatedScoreEntry
9
{
10
    GENERATED_BODY()
11

12
    UPROPERTY()
13
    FName PlayerId = NAME_None;
14

15
    UPROPERTY()
16
    int32 Score = 0;
17
};
18

19
UCLASS()
20
class YOURGAME_API AReplicatedScoreboard : public AActor
21
{
22
    GENERATED_BODY()
23

24
public:
25
    AReplicatedScoreboard();
26

27
    void SetScore(FName PlayerId, int32 NewScore);
28

29
    virtual void GetLifetimeReplicatedProps(
30
        TArray<FLifetimeProperty>& OutLifetimeProps) const override;
31

32
protected:
33
    UPROPERTY(ReplicatedUsing = OnRep_ScoreEntries)
34
    TArray<FReplicatedScoreEntry> ScoreEntries;
35

36
    UFUNCTION()
37
    void OnRep_ScoreEntries();
38

39
private:
40
    // 네트워크로 보내지 않는 로컬 조회 캐시다.
41
    TMap<FName, int32> ScoreByPlayer;
42

43
    void RebuildScoreCache();
44
};

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

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

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

16
void AReplicatedScoreboard::SetScore(FName PlayerId, int32 NewScore)
17
{
18
    if (!HasAuthority() || PlayerId.IsNone())
19
    {
20
        return;
21
    }
22

23
    FReplicatedScoreEntry* Entry = ScoreEntries.FindByPredicate(
24
        [PlayerId](const FReplicatedScoreEntry& Candidate)
25
        {
26
            return Candidate.PlayerId == PlayerId;
27
        });
28

29
    if (Entry)
30
    {
31
        Entry->Score = NewScore;
32
    }
33
    else
34
    {
35
        ScoreEntries.Add({PlayerId, NewScore});
36
    }
37

38
    // RepNotify는 서버에서 자동 호출되지 않으므로 서버 캐시도 직접 갱신한다.
39
    RebuildScoreCache();
40
    ForceNetUpdate();
41
}
42

43
void AReplicatedScoreboard::OnRep_ScoreEntries()
44
{
45
    RebuildScoreCache();
46
}
47

48
void AReplicatedScoreboard::RebuildScoreCache()
49
{
50
    ScoreByPlayer.Reset(ScoreEntries.Num());
51

52
    for (const FReplicatedScoreEntry& Entry : ScoreEntries)
53
    {
54
        if (!Entry.PlayerId.IsNone())
55
        {
56
            // 이 예제의 중복 정책은 last-wins다.
57
            ScoreByPlayer.Add(Entry.PlayerId, Entry.Score);
58
        }
59
    }
60
}

이 예제에서 중요한 것은 문법보다 데이터 계약이다.

• ScoreEntries만 복제되는 정본이다. ScoreByPlayer는 파생 캐시다.
• 서버만 정본을 변경한다. 클라이언트의 요청이 필요하면 Server RPC로 보내고 서버에서 소유권, 범위, 빈도를 검증한다.
• 같은 키가 두 번 들어왔을 때 이 예제는 마지막 값을 사용한다. 데이터에 따라 첫 값을 유지하거나 전체 업데이트를 거부할 수도 있다.
• TMap과 TSet의 순회 순서는 안정적인 표시 순서가 아니다. 순서가 의미 있으면 명시적인 정렬 키를 복제한 뒤 정렬한다.
• 프로퍼티 복제는 최종 상태를 수렴시킨다. 모든 중간 변경이나 이벤트 순서를 보장하지 않는다.

여러 항목이 동시에 바뀌어야만 유효한 불변식이 있다면 수신 중간 상태를 그대로 적용하지 말고 revision을 함께 보내거나 하나의 항목 구조체로 묶어 검증한 뒤 캐시를 교체한다. ordered event stream이 필요하다면 상태 복제만으로 대신하지 않는다.

변경이 잦거나 큰 상태: Fast Array#

항목이 많고 추가·수정·삭제가 자주 일어나면 일반 배열 스냅샷보다 FFastArraySerializer를 고려한다. Fast Array는 바뀐 항목을 추적하는 복제 패턴을 제공한다.

다만 이름만 바꾸면 자동으로 효율적이 되는 기능은 아니다.

• 항목 타입은 FFastArraySerializerItem을 상속하고 컬렉션은 FFastArraySerializer를 상속한다.
• 항목을 추가하거나 수정한 뒤 MarkItemDirty를 호출한다.
• 삭제처럼 배열 구조 전체의 변경을 알릴 때는 올바른 API와 MarkArrayDirty를 사용한다.
• 서버와 클라이언트의 배열 인덱스나 순서가 같다고 가정하지 않는다. 게임 도메인의 안정적인 키를 별도 필드로 둔다.
• 수신 콜백에서는 추가, 변경, 삭제에 따른 로컬 캐시와 UI를 명시적으로 갱신한다.

아래 기준으로 선택한다.

사용자 정의 NetSerialize도 가능하지만 기본 해법으로 삼기 어렵다. 항목 수 상한, 중복 키, 잘못된 enum과 object reference, 정수 overflow를 역직렬화 전에 검증해야 하며 사용하는 엔진 버전과의 호환성도 직접 확인해야 한다.

2. BeginPlay 전에 값을 전달하는 Deferred Spawn#

일반 SpawnActor는 생성과 Construction Script, 컴포넌트 초기화까지 한 호출 흐름에서 진행한다. 이미 플레이 중인 월드라면 호출이 반환되기 전에 BeginPlay까지 실행될 수 있으므로, 반환된 포인터에 초기값을 넣는 것은 늦다.

Deferred Spawn은 생성자를 미루는 API가 아니다. SpawnActorDeferred가 반환할 때 네이티브 생성자와 기본 서브오브젝트 생성, PostSpawnInitialize, PostActorCreated까지 진행됐다. 대신 Blueprint Construction Script와 OnConstruction, 이후 컴포넌트 초기화와 BeginPlay로 가는 단계를 멈춘다. 반환값은 유효하지만 아직 완성되지 않은 Actor다.

1
AConfiguredProjectile* SpawnConfiguredProjectile(
2
    UWorld* World,
3
    TSubclassOf<AConfiguredProjectile> ProjectileClass,
4
    const FTransform& SpawnTransform,
5
    AActor* Owner,
6
    APawn* Instigator,
7
    const FProjectileSpawnConfig& InitialConfig)
8
{
9
    // 복제되는 authoritative Actor는 서버에서만 생성한다.
10
    if (!World || World->GetNetMode() == NM_Client || !*ProjectileClass ||
11
        SpawnTransform.ContainsNaN())
12
    {
13
        return nullptr;
14
    }
15

16
    AConfiguredProjectile* Projectile =
17
        World->SpawnActorDeferred<AConfiguredProjectile>(
18
            ProjectileClass,
19
            SpawnTransform,
20
            Owner,
21
            Instigator,
22
            ESpawnActorCollisionHandlingMethod::AdjustIfPossibleButDontSpawnIfColliding);
23

24
    if (!Projectile)
25
    {
26
        return nullptr;
27
    }
28

29
    // OnConstruction과 BeginPlay가 읽어야 하는 필수 값을 여기서 넣는다.
30
    Projectile->SetSpawnConfigBeforeFinish(InitialConfig);
31

32
    Projectile->FinishSpawning(SpawnTransform);
33

34
    // 선택한 충돌 정책에 따라 finish 중 파괴될 가능성까지 확인한다.
35
    return IsValid(Projectile) ? Projectile : nullptr;
36
}

ExposeOnSpawn과 replication은 별개의 기능이다#

다음 metadata는 Blueprint의 Spawn Actor 노드에 입력 핀을 만든다.

1
UPROPERTY(
2
    EditAnywhere,
3
    BlueprintReadWrite,
4
    ReplicatedUsing = OnRep_SpawnConfig,
5
    meta = (ExposeOnSpawn = "true"))
6
FProjectileSpawnConfig SpawnConfig;

Blueprint의 Spawn Actor 노드는 내부적으로 Begin Deferred Spawn, 노출된 프로퍼티 대입, Finish Spawning 순으로 확장되므로 Construction Script에서 핀 값을 읽을 수 있다. 그러나 ExposeOnSpawn은 editor metadata일 뿐이다.

• C++ SpawnActorDeferred가 값을 자동으로 채워 주지 않는다.
• 프로퍼티를 자동으로 복제하지 않는다. Replicated 또는 ReplicatedUsing 선언과 DOREPLIFETIME이 별도로 필요하다.
• 생성자는 spawn 시 전달된 값을 볼 수 없다. 생성자는 deferred 반환 전에 이미 실행됐다.

네트워크 Actor에서는 Construction Script의 부작용 자체가 복제된다고 가정해서도 안 된다. 서버에서 deferred 구간에 값을 넣으면 서버의 OnConstruction은 그 값을 보지만, 클라이언트 proxy의 Construction Script는 초기 replicated property가 적용되기 전에 실행될 수 있다. 런타임 게임 상태는 ReplicatedUsing과 OnRep에서 다시 적용하고, 초기값이 CDO와 같아 알림이 생략되는 경우까지 고려한다면 BeginPlay에서도 최종 상태를 확인한다. 서버에서는 RepNotify가 자동 호출되지 않으므로 명시적인 적용 함수나 OnConstruction을 함께 사용한다.

네트워크와 생명주기 체크리스트#

참고 자료#

• Epic Games: UE-137102 — TMap properties cannot be replicated
• Epic Games: Actor Lifecycle
• Epic Games: UWorld::SpawnActorDeferred
• Epic Games: Actor Property Metadata Specifiers
• Unreal Engine 4 Network Compendium
• 프로그래머를 괴롭히는 Unreal Engine 4의 함정들
• 언리얼 네트워킹 아키텍처

Epic Games의 Unreal Engine GitHub 소스 링크는 Epic 계정과 연결된 GitHub 로그인이 필요할 수 있다.