UEFN AddItem Far Distance 버그 해결: Spatial Replication Desync 문제의 수정

Verse에서 커스텀 item prefab을 스폰하고, 이를 플레이어의 hotbar에 추가했는데... 아무 일도 일어나지 않습니다. 플레이어의 인벤토리는 비어 있거나, 아이템 아이콘이 깨진 흰색 사각형으로 표시됩니다. 하지만 플레이어가 맵의 원점인 {0.0, 0.0, 0.0}으로 돌아가면 아이템이 마법처럼 나타납니다. 만약 uefn additem far distance bug로 어려움을 겪고 있다면, 이는 UEFN의 spatial streaming 규칙과 충돌하는 Unreal Engine의 핵심 network replication 설계와 씨름하고 있는 것입니다.

Fortnite Creative의 Spatial Streaming 이해하기

Fortnite 맵은 메모리를 절약하기 위해 동적 컴포넌트를 실시간으로 로드 및 언로드해야 하는 거대한 환경입니다. 서버 틱을 안정적으로 유지하고 클라이언트 프레임 레이트를 높이기 위해, UEFN은 World Partition 기반의 spatial streaming 시스템을 활용합니다. 서버는 단순히 모든 actor를 항상 모든 클라이언트에 replicate하지 않습니다. 대신, 어떤 데이터 패키지를 어떤 플레이어에게 전송할지 결정하는 network relevancy 규칙에 의해 replication이 제어됩니다.

World Partition 및 Network Relevancy Distance

표준 Fortnite 설정에서 NetRelevancyDistance는 actor가 플레이어에게 replicate되는 반경입니다. 만약 엔티티가 이 범위(일반적으로 약 15,000 Unreal Units 또는 150미터) 외부에서 스폰되면, 서버는 해당 replication 데이터를 클라이언트로 전송하지 않습니다. 이러한 공간적 최적화는 오픈 월드 맵에서 활성 replication 채널을 최대 80%까지 줄여줍니다. 그러나 이는 클라이언트가 먼 좌표에 존재하는 엔티티를 완전히 인식하지 못할 수 있음을 의미하기도 합니다.

플레이어가 맵을 횡단할 때, 클라이언트는 서버에 그리드 셀을 동적으로 요청합니다. 플레이어의 클라이언트에 현재 스트리밍되지 않은 그리드 셀에서 엔티티가 스폰되면, 클라이언트는 그 존재를 감지하지 못합니다. 이 culling은 귀중한 GPU 메모리를 절약하고 원거리의 draw call로 인해 rendering pipeline이 병목을 겪는 것을 방지합니다.

UEFN의 Entity Instantiation 처리 방식

UEFN에서 커스텀 item prefab은 기본 엔티티와 item_component, mesh_component, icon_component와 같은 컴포넌트의 결합으로 구성됩니다. Verse 스크립트가 이러한 prefab 중 하나를 인스턴스화할 때, 서버는 메모리에 엔티티 컨테이너와 그 하위 컴포넌트들을 생성합니다. 그러나 이러한 렌더링 컴포넌트가 클라이언트로 실제로 replication되는 것은 여전히 엔티티의 공간적 transform에 묶여 있습니다. 해당 transform이 플레이어로부터 너무 멀리 떨어져 있으면, 클라이언트는 컴포넌트의 존재를 절대 전달받지 못합니다.

AddItem Distance 버그 분석

이 문제는 공간적 엔티티 스폰과 플레이어 인벤토리 시스템을 함께 사용할 때 발생합니다. 인벤토리 hotbar 컴포넌트는 플레이어의 캐릭터에 직접 어태치되어 있으므로 globally replicate됩니다. 원거리에서 AddItem()을 실행하면, globally relevant한 컨테이너와 spatially culled된 에셋 사이에 직접적인 desync가 발생하게 됩니다.

오류 루프의 단계별 분석

이 desync가 발생할 때 내부적으로 어떤 일이 일어나는지 정확히 살펴보겠습니다:

• Spawning: Verse 스크립트가 {X:=0.0, Y:=0.0, Z:=25000.0}과 같이 멀리 떨어진 좌표에 item prefab을 스폰합니다.
• Inventory Call: 스크립트가 플레이어의 fort_inventory_weapon_hotbar_component에 대해 즉시 AddItem()을 호출합니다.
• UI Registration: 클라이언트 측 인벤토리 UI가 새로운 아이템이 hotbar 슬롯을 차지했다는 replication 이벤트를 수신합니다.
• Null Lookup: 클라이언트가 렌더링을 위해 icon_component를 로드하고자 아이템의 참조(reference)를 확인(resolve)하려 시도합니다.
• Visual Glitch: 거리 culling으로 인해 스폰된 엔티티가 클라이언트에 replicate되지 않았기 때문에, 참조 확인에 실패하고 빈 슬롯이 렌더링됩니다.

심층 분석: UEFN 컴포넌트 생명주기 및 UI 바인딩

UEFN에서 mesh_component 및 icon_component와 같은 컴포넌트는 클라이언트 측 rendering pipeline에 직접 바인딩됩니다. UI는 현재 hotbar에 있는 아이템의 icon_component에서 아이콘을 직접 가져오는 Slate UI widgets을 사용하여 구축됩니다. hotbar 컴포넌트에 상태 변경(예: 아이템 추가 또는 제거)이 발생하면 내부 replication 이벤트를 발생시킵니다. 클라이언트 측 UI는 이 이벤트를 수신하여 UI 슬롯을 다시 그립니다.

그러나 UI 다시 그리기가 replication 이벤트를 수신하는 즉시 발생하기 때문에, 클라이언트는 참조된 아이템 엔티티로부터 아이콘 텍스처에 액세스하려고 시도합니다. 만약 아이템 엔티티의 replication 채널이 아직 열리지 않았다면, 텍스처 포인터가 유효하지 않게 되어 아이템이 누락되거나 깨지는 버그가 발생합니다. 인벤토리 시스템은 컴포넌트에 soft object references를 사용하여 정상적으로 실패 처리(즉, 게임이 크래시되지 않음)하도록 지원하지만, 그 결과 "보이지 않는 아이템" 버그가 발생하게 됩니다.

클라이언트 측 Slate UI가 업데이트 지침을 받으면 아이템 참조를 확인합니다. 기본 actor가 아직 스트리밍되거나 replicate되지 않은 경우, 클라이언트 UI 엔진은 어쩔 수 없이 null 표현이나 임시 비주얼 스텁(visual stub)을 할당해야 합니다. 이로 인해 빈 슬롯이 나타나며, 이 슬롯은 replication 채널이 명시적으로 설정된 후에야 채워집니다. 표준 Unreal Engine에서는 개발자가 actor replication에 콜백을 수동으로 등록할 수 있지만, UEFN의 Verse API는 현재 이를 추상화하여 제공하므로 개발자가 컴포넌트 replication에 대한 직접적인 listener를 구현할 수 없습니다.

미스터리한 월드 원점 {0.0, 0.0, 0.0} 동작 방식

많은 개발자가 플레이어가 {0.0, 0.0, 0.0} 좌표 원점에 가까워질 때 이 버그가 저절로 해결되는 현상을 목격합니다. Unreal Engine의 replication 모델에서, 공간적 부모(spatial parent)가 확인되지 않았거나 물리 레이어(physics layer)가 초기화되지 않은 actor들은 복제된 transform의 기본값이 원점으로 설정됩니다. 이로 인해 원점은 큐에 대기 중인 replication 업데이트의 핫스팟이 됩니다. 플레이어 캐릭터가 {0.0, 0.0, 0.0}에 접근하면, 엔진은 이러한 확인되지 않은 참조를 위한 replication 채널을 열어 아이템 데이터의 다운로드를 강제합니다.

이러한 동작은 Unreal Engine network driver의 알려진 특이 현상(quirk)입니다. spatial streaming이 replicate된 actor의 transform을 확인하지 못하면, 좌표를 기본 float 값으로 떨어뜨립니다. 플레이어가 보통 원점 근처를 지나가거나 원점이 특정 글로벌 매니저 actor들에게 항상 relevant한 것으로 간주되기 때문에, 클라이언트는 결국 채널을 열게 됩니다. 이 채널이 열리면 보류 중인 모든 컴포넌트 데이터가 한 번에 replicate되어 아이템이 갑자기 나타납니다.

multiplayer 게임 개발에서 spatial replication이 골칫거리를 유발한 것은 이번이 처음이 아닙니다. 예를 들어, 거대한 지형에서 고속으로 이동하는 플레이어 캐릭터나 원격 트리거를 처리할 때 위치 오차가 빈번히 발생하며, 이에 대해서는 UEFN 및 Unreal Engine multiplayer에서 플레이어 위치 desync를 해결하는 방법 가이드에서 자세히 설명한 바 있습니다. 마찬가지로, 아이템이 서로 다른 actor 간에 전달될 때 컴포넌트 소유권이 꼬일 수 있는데, 이 주제는 Unreal Engine에서의 Unreal Engine에서 multiplayer 인벤토리 문제 및 뒤바뀐 actorcomponent 소유자 해결 방법 해결 가이드에서 상세히 다루고 있습니다.

엔진 레벨의 해결 방법 및 우회책

순수 제공 툴(native tools)을 사용하여 uefn additem far distance bug를 해결하려면, 인벤토리 함수를 호출하기 전에 엔티티가 클라이언트에 relevant한지 확인해야 합니다. UEFN은 Verse에 직접적인 로우 레벨 replication 제어 기능(bAlwaysRelevant 또는 수동 relevancy 그룹 등)을 노출하지 않으므로, 기발한 공간적 우회책을 사용해야 합니다. 다음은 이 문제를 해결하는 가장 안정적인 세 가지 방법입니다.

전략 1: 로컬 플레이어 앵커링 (Local Player Anchoring)

가장 신뢰할 수 있는 엔진 수준 솔루션은 대상 플레이어의 현재 변환 좌표(translation coordinates)에 직접 item prefab을 스폰하는 것입니다. 플레이어는 항상 본인의 net relevancy 범위 내에 있으므로, 서버는 즉시 엔티티와 그 컴포넌트를 클라이언트에 replicate합니다. 클라이언트가 엔티티를 등록하고 나면, AddItem()을 실행하여 아이템을 hotbar에 안전하게 삽입할 수 있습니다. 이제 인벤토리 시스템이 아이템을 소유하므로, 해당 아이템의 spatial replication이 플레이어에게 고정(anchored)되어 맵 어디로 이동하든 아이템의 비주얼 에셋을 잃지 않게 됩니다.

전략 2: 지연된 상태 할당 (Delayed State Allocation)

만약 게임 로직상 멀리 떨어진 상자(chest) 위치에서 아이템을 스폰해야 한다면, hotbar에 아이템을 추가하는 것을 연기해야 합니다. 엔티티가 스폰되는 즉시 AddItem()을 호출하는 대신, 플레이어가 상자의 특정 근접 임계값 내에 들어올 때까지 기다리십시오. 커스텀 Verse 트리거 또는 거리 체크 루프를 통해 이 임계값을 관리할 수 있습니다. 플레이어가 relevancy 반경(10,000 유닛 이내)에 진입하면 엔티티가 replicate되고, 이때 안전하게 인벤토리 이전을 트리거할 수 있습니다.

전략 3: 클라이언트 측 UI 재초기화 (Client-Side UI Re-initialization)

원거리에서의 아이템 스폰을 피할 수 없는 경우, 엔티티가 replicate된 후 클라이언트 UI를 강제로 다시 그리도록 할 수 있습니다. 플레이어가 스폰 영역에 접근할 때 발생하는 커스텀 이벤트를 감수함으로써 이를 구현할 수 있습니다. 플레이어가 엔티티를 스트리밍하기에 충분히 가까워지면 Verse 스크립트가 replicated UI 상태 변수를 업데이트합니다. 이를 통해 커스텀 HUD widget이 인벤토리 컴포넌트를 다시 평가하고 올바른 텍스처를 그리도록 강제합니다.

Verse 코드 구현: 안전한 로컬 스포닝

다음 Verse 스크립트는 인벤토리에 추가하기 전에 플레이어의 정확한 좌표에 커스텀 엔티티 prefab을 스폰하는 방법을 보여줍니다. 이 방식은 플레이어의 활성 네트워크 범위 내에서 즉각적으로 replication이 일어나도록 강제함으로써 거리 culling 문제를 우회합니다.

using { /Fortnite.com/Devices }
using { /Fortnite.com/Characters }
using { /Fortnite.com/Playspaces }
using { /Verse.org/Simulation }
using { /Verse.org/SpatialMath }

# Custom device to safely manage item spawning and inventory allocation
inventory_spawner_device := class(creative_device):

    # Reference to the custom item prefab asset
    @editable
    ItemPrefab : entity_prefab = entity_prefab{}

    # Triggers the item generation and addition to the player's inventory
    GiveItemToPlayer(Player : player) : void =
        if (FortChar := Player.GetFortCharacter[]):
            # Get the player's current location to bypass spatial culling
            PlayerLocation := FortChar.GetTransform().Translation
            
            # Spawn the item prefab directly at the player's position.
            # This guarantees that the entity falls within the client's network relevancy bubble.
            SpawnResult := SpawnEntity(ItemPrefab, PlayerLocation, IdentityRotation())
            
            if (SpawnedEntity := SpawnResult?):
                # Retrieve the item component from the spawned entity
                if (ItemComponent := SpawnedEntity.GetComponent(item_component[])):
                    # Get the player's hotbar inventory component
                    if (InventoryComponent := FortChar.GetInventoryComponent[fort_inventory_weapon_hotbar_component]):
                        # Safely add the item to the hotbar.
                        # Since the entity was spawned locally, the client has already replicated
                        # its icon_component and mesh_component, preventing desyncs.
                        InventoryComponent.AddItem(ItemComponent)
                        Print("Successfully added item to hotbar without desync.")
                    else: 
                        Print("Error: Could not locate fort_inventory_weapon_hotbar_component.")
                else:
                    Print("Error: Spawned entity is missing item_component.")
            else:
                Print("Error: Failed to spawn the entity prefab.")

horizOn을 사용한 인벤토리 상태 디커플링

이러한 엔진 수준의 replication 우회책을 관리하는 것은 맵이 커지고 복잡한 게임플레이 메커니즘을 도입함에 따라 빠르게 번거로워질 수 있습니다. 게임에 지속적인 인벤토리(persistent inventories), 매치 간 진행 상황(cross-match progression) 또는 거래 시스템이 필요한 경우, 인벤토리 상태를 위해 물리적인 actor replication에 의존하는 것은 거대한 병목 현상을 초래합니다.

이때 horizOn과 같은 전문화된 backend가 유용해집니다.

단순히 데이터를 추출하기 위해 원거리 좌표에 물리적 엔티티를 실제로 스폰하는 대신, horizOn을 사용하면 Unreal의 actor replication pipeline에서 게임 상태를 분리(decouple)할 수 있습니다.

플레이어가 아이템을 획득하거나 구매하면, 게임 서버는 가벼운 API 호출을 수행하여 horizOn에 있는 플레이어 프로필을 업데이트합니다. 클라이언트 측 UI는 backend에서 이 상태를 직접 읽어 네트워크를 통해 actor를 replicate할 필요 없이 로컬 정적 에셋을 사용하여 아이템을 렌더링합니다.

이 아키텍처는 거리 관련 desync를 방지하고, 인벤토리 데이터를 안전하게 저장하며, 서버의 네트워크 부하를 획기적으로 줄여줍니다.

고성능 UEFN Networking을 위한 모범 사례

UEFN 내에서 spatial replication을 수동으로 관리하기로 선택한 경우, 네트워크 오버헤드와 desync를 최소화하기 위해 다음 업계 모범 사례를 따르십시오:

1. Always Instantiate Locally: 일시적인 아이템 스포너를 플레이어 캐릭터 가까이에 유지하여 즉각적인 replication을 보장하십시오.
2. Implement Visual Fallbacks: 아이템의 컴포넌트가 아직 replicate되지 않은 경우를 대비해 자리 표시자(placeholder) 아이콘을 렌더링하도록 커스텀 UI widgets을 설계하십시오.
3. Decouple Data from Visuals: Verse struct를 사용하여 아이템의 논리적 상태(내구도, 개수, 능력치)를 관리하고, 엔티티는 시각적 표현으로만 사용하십시오.
4. Throttle Inventory Operations: 네트워크 직렬화(serialization) 큐가 과부하 상태에서 업데이트를 누락할 수 있으므로, AddItem() 또는 RemoveItem()을 너무 빠른 간격으로 연속 호출하는 것을 피하십시오.

결론 및 다음 단계

uefn additem far distance bug와 같은 spatial replication 버그는 로컬 엔진의 한계가 플레이어 경험을 얼마나 쉽게 방해할 수 있는지 보여줍니다. UEFN에서 network relevancy 및 World Partition이 작동하는 방식을 이해하면 클라이언트와 서버 상태를 조화롭게 유지하는 스마트한 스폰 흐름을 설계할 수 있습니다. 영구적인 상태(persistent states), 글로벌 플레이어 프로필, 안전한 경제 시스템이 필요한 대규모 게임을 제작하는 개발자에게는 엔진 레벨의 replication을 넘어서는 것이 궁극적인 해결책입니다.

multiplayer backend를 확장할 준비가 되셨나요? horizOn을 무료로 체험해 보거나 API docs를 확인해 보세요.

---

Source: Adding Item not working in far distance