UEFN에서 플레이어가 퇴장할 때 Verse weak_map은 자동으로 정리될까?

AI coding assistant가 포트나이트 섬에서 플레이어가 연결을 끊는 즉시 Verse가 weak_map에서 플레이어 데이터를 자동으로 제거한다고 말하더라도, 이를 그대로 믿는다면 심각한 runtime crash를 겪게 될 것입니다. weak reference를 사용하므로 플레이어 오브젝트가 Garbage Collection될 때 엔진이 해당 키를 정리할 것이라는 주장은 얼핏 논리적으로 들립니다. 하지만 Unreal Editor for Fortnite (UEFN)의 실제 메커니즘은 훨씬 복잡하며, Verse memory manager가 플레이어 lifecycle을 처리하는 방식을 오해하면 감지하기 어려운 state leak와 치명적인 예외가 발생할 수 있습니다.

플레이어가 퇴장한 후 맵에서 만료된 오브젝트를 참조하면 악명 높은 ErrRuntime_WeakMapInvalidKey가 발생하거나 섬 전체가 다운되는 크래시로 이어질 수 있습니다. 이 경우 서버 안정성을 유지하기 위해 엄격한 UEFN server crash fix protocol을 구현해야 할 수도 있습니다. 이러한 문제를 방지하려면 개발자는 Verse가 내부적으로 메모리를 관리하는 방식을 이해하고 확실한 정리(cleanup) 루틴을 구현하는 방법을 배워야 합니다.

The Misconception: AI-Generated Advice vs. Verse Reality

많은 개발자가 플레이어가 매치를 떠날 때 해당 플레이어의 맵 데이터를 어떻게 처리해야 하는지 AI assistant에 질문합니다. 흔히 접하는 AI의 답변 중 하나는 엔진이 플레이어 키를 "weak reference"로 처리하여 플레이어가 퇴장할 때 맵에서 해당 엔트리를 자동으로 제거한다는 것입니다. 하지만 이는 완전히 잘못된 사실입니다.

Verse의 weak_map(player, t)은 내부적으로 Garbage Collection을 차단하는 강한 참조 순환(hard reference cycles)을 방지하기 위해 플레이어 키를 weak reference로 사용하지만, 맵 엔트리 자체를 자동으로 즉시 정리하지는 않습니다. 키 슬롯과 관련 데이터를 모두 포함하는 엔트리는 맵 컨테이너에 여전히 할당된 상태로 유지됩니다.

플레이어가 떠난 후 코드에서 해당 키에 접근하거나 값을 평가 또는 수정하려고 하면, Verse 런타임은 null이거나 유효하지 않은 플레이어 오브젝트의 dereference를 시도합니다. 이때 런타임은 안전하게 실패(fail gracefully)하는 대신 크래시를 일으키거나 catch할 수 없는 예외(exception)를 발생시킵니다. 시스템은 개발자가 자동 정리에 의존하기보다 lifecycle 전환을 명시적으로 처리할 것을 요구합니다.

Why Weak Maps Do Not Auto-Clean Player Entries

이러한 현상이 발생하는 이유를 이해하려면 UEFN에서 weak_map의 목적을 살펴보아야 합니다. weak map이 일시적인 메모리 캐시로 사용되는 일반적인 프로그래밍 환경과 달리, Verse는 weak_map(player, t)을 주로 **영구 플레이어 데이터(persistent player data)**의 게이트키퍼로 사용합니다.

Persisting Across Play Sessions

모듈 스코프에 선언된 weak_map(player, t)을 사용하면 엔진은 해당 값을 Epic의 영구 클라우드 데이터베이스에 연동합니다. 만약 플레이어가 매치를 나갔다가 3일 후에 다시 돌아오더라도, 엔진은 해당 플레이어의 ID를 영구 맵 키와 매칭하여 이전 진행 상황을 복구합니다.

만약 플레이어가 게임을 떠나는 즉시 엔진이 맵에서 플레이어 엔트리를 자동으로 삭제한다면, 맵의 모든 영구 데이터가 손실될 것입니다. 플레이어의 연결이 끊어지거나 네트워크 타임아웃이 발생할 때마다 레벨, 커스텀 재화, 해제한 아이템 등이 모두 초기화됩니다. 따라서 데이터베이스는 연결 끊김이 발생하더라도 데이터를 보존하도록 설계되어 있어 해당 엔트리를 그대로 유지합니다.

The Scoped Lifetime of Player Objects

플레이어가 매치를 떠나면 playspace에 있는 활성 세션 오브젝트가 파괴됩니다. 이로 인해 Verse 코드에 유지되고 있던 실제 player 참조는 무효한 핸들(dead handle)이 됩니다.

이제 맵의 키가 유효하지 않고 비활성화된 오브젝트를 가리키기 때문에, 이 무효한 참조로 맵을 쿼리하면 실패하게 됩니다. 엔진은 실시간으로 맵에서 무효한 키를 찾아 지우는 작업을 수행하지 않습니다. 대신 비활성 상태로 방치하므로, 만료된 참조(stale reference)가 누적되는 것을 방지하려면 수동 관리가 필수적입니다.

The Consequences: Memory Leaks, Stale Data, and Server Crashes

플레이어 엔트리를 정리하지 않으면 장시간 진행되는 매치에서 게임 성능과 서버 안정성을 저하시키는 세 가지 명확한 문제가 발생합니다.

• Stale Data Leakage: 플레이어가 퇴장한 후 다른 플레이어가 입장할 때 엔진이 내부 플레이어 슬롯을 재사용하면 새 플레이어가 이전 플레이어의 세션 데이터를 상속받을 수 있습니다. 이는 새 플레이어가 가득 찬 인벤토리를 가지고 스폰되거나 잘못된 매치 스탯을 갖게 되는 등의 상태 버그(state bug)로 이어집니다.
• Memory Accumulation: 단일 boolean이나 integer는 미미한 공간을 차지하지만, 동시 접속자가 많은 로비에서 최대 50명의 플레이어를 위해 복잡한 구조체를 저장하면 메모리 사용량이 크게 증가할 수 있습니다. 4시간 동안 지속되는 서버 세션 동안 이러한 메모리 누적은 서버 tick rate를 저하시킬 수 있습니다.
• Look-up Failures: 비활성화된 플레이어의 상태를 조회하거나 유효하지 않은 플레이어 참조에서 함수를 호출하려고 시도하면 즉시 런타임 크래시가 발생합니다.

Hitting the Epic Cloud Save Limits

UEFN은 영구 데이터에 엄격한 제한을 둡니다. 섬당 최대 4개의 persistent weak_map으로 제한되며, 각 플레이어의 개별 레코드 크기는 256 KB 데이터를 초과할 수 없습니다.

임시 세션 상태를 저장하기 위해 영구 weak_map을 사용하면 이 귀중한 데이터베이스 공간을 낭비하게 됩니다. 모든 업데이트가 Epic의 데이터베이스에 기록되므로 쓰기 제한(write-throttling) 페널티를 받거나 256 KB 한도를 초과할 위험이 있으며, 추가 데이터를 쓰려고 할 때 런타임 에러가 발생합니다.

Step-by-Step Tutorial: Managing Player Session States Safely

memory leak나 데이터베이스 비대화의 위험 없이 플레이어 상태를 관리하려면, 일시적인 세션 데이터와 영구 클라우드 데이터를 분리해야 합니다. 일시적인 데이터는 비영구적인 일반 맵에 저장해야 하며, 플레이어가 연결을 끊을 때 수동으로 정리해야 합니다.

Step 1: Define Your Session State Struct

단일 라운드나 매치 동안 플레이어에게 필요한 모든 변수를 포함하는 비영구적 구조체(struct)를 정의하는 것부터 시작합니다. 이 클래스나 구조체에는 <persistable>을 붙이지 마십시오.

# Define the transient data structure for active gameplay tracking
player_session_state := struct:
    IsMoneyBagFull : logic = false
    CurrentGold : int = 0
    SpawnTime : float = 0.0

Step 2: Establish the Manager Device

코디네이터 역할을 할 creative device를 생성합니다. 이 디바이스는 활성 플레이어의 수정 가능한 비영구적 맵을 보유하게 됩니다. Verse의 일반 맵은 불변(immutable)이므로, 플레이어가 참여하거나 나갈 때 맵을 덮어쓸 수 있도록 맵 변수를 var로 선언합니다.

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

# Device handling player lifecycle events and session state mapping
state_manager_device := class(creative_device):

    # Non-persistent map for tracking active player sessions
    var SessionStates : [player]player_session_state = map{}

Step 3: Subscribe to Playspace Events

OnBegin 함수에서 playspace의 연결 이벤트들을 구독합니다. 이를 통해 플레이어가 참여할 때 초기화 코드를 실행하고, 떠날 때 정리 코드를 실행할 수 있습니다.

    OnBegin<override>()<suspends>:void=
        GetPlayspace().PlayerAddedEvent().Subscribe(OnPlayerAdded)
        GetPlayspace().PlayerRemovedEvent().Subscribe(OnPlayerRemoved)
        
        # Initialize any players already in the session (useful for UEFN hot-reloading)
        for (Player : GetPlayspace().GetPlayers()):
            OnPlayerAdded(Player)

Step 4: Implement Registration and Cleanup Logic

플레이어가 참가하면 맵에 기본 세션 상태를 입력합니다. 퇴장할 때는 맵에서 그 엔트리를 삭제해야 합니다. Verse에는 기본 제공되는 Map.Remove() 함수가 없기 때문에, 나가는 플레이어를 필터링하여 맵을 재구성해야 합니다. 이를 통해 stale reference가 메모리에 남아 있는 것을 방지할 수 있습니다.

    # Triggered when a player connects to the server
    OnPlayerAdded(Player: player):void=
        if (not SessionStates[Player]):
            InitialState := player_session_state{IsMoneyBagFull := false, CurrentGold := 0, SpawnTime := GetEngineTime()}
            if (set SessionStates[Player] = InitialState):
                Print("Initialized gameplay state for joining player.")

    # Triggered when a player disconnects or leaves the game
    OnPlayerRemoved(Player: player):void=
        Print("Player disconnected. Initiating map cleanup.")
        RemovePlayerSession(Player)

    # Purges the player's entry by reconstructing the map
    RemovePlayerSession(PlayerToRemove: player):void=
        var CleanedStates : [player]player_session_state = map{}
        for (ActivePlayer -> State : SessionStates):
            # Copy all players except the one who left
            if (ActivePlayer <> PlayerToRemove):
                if (set CleanedStates[ActivePlayer] = State):
                    # Entry successfully migrated to the cleaned map
        
        set SessionStates = CleanedStates
        Print("Successfully removed player session entry from memory.")

플레이어가 나갈 때 맵을 재구성함으로써 참조 키를 완전히 삭제할 수 있습니다. 이렇게 하면 Garbage Collector가 게임 루프에 stale entry를 남기지 않고 플레이어 리소스를 회수할 수 있습니다.

이러한 lifecycle 전환 과정에서 커스텀 텔레메트리(telemetry)를 추적하고 싶다면, 세션 길이 또는 재화 통계를 외부 Backend에 보고할 때 32-character analytics event name limit in Verse와 같은 한도 제한도 염두에 두어야 합니다.

Best Practices for Verse State Management

UEFN 서버의 안정성과 성능을 보장하기 위해, 플레이어 데이터 관리 시 다음 가이드라인을 준수하십시오.

1. Differentiate Session vs. Persistent Data: 현재 매치의 체력, 라운드 점수, 임시 위치와 같은 수명이 짧은 변수들을 persistent weak_map에 저장해서는 안 됩니다. 임시 상태는 매니저 클래스 내에 래핑된 일반 mutable 맵에 보관하십시오.
2. Verify Player Activity with IsActive: 맵에서 플레이어 데이터를 가져오거나 수정하기 전에 IsActive[] 쿼리를 사용하여 해당 플레이어가 여전히 playspace에 존재하는지 확인하십시오. 만약 IsActive[]가 false를 반환하면 조회를 중단하고 정리(cleanup) 이벤트를 실행하십시오.
3. Monitor Data Sizes with FitsInPlayerMap: persistent weak_map에 기록할 때 FitsInPlayerMap()을 호출하여 업데이트가 256 KB 제한을 초과하지 않는지 확인하여 런타임 예외를 예방하십시오.
4. Consolidate Your Maps: 모든 변수마다 개별 맵을 생성하지 마십시오. 모든 플레이어 변수를 포함하는 단일 클래스를 정의하고 플레이어를 해당 클래스에 매핑하십시오. 이렇게 하면 맵의 개수를 최소화하고 섬당 최대 4개의 persistent weak map 제한을 준수할 수 있습니다.

Offloading Complexity to a Reliable Cloud Backend

Verse에서 플레이어 세션 lifecycle, 데이터베이스 제한, 수동 정리 로직을 관리하는 것은 금방 복잡해질 수 있습니다. 세션 간 진행 상황(cross-session progression), 전역 동기화 인벤토리, 또는 리전별 Matchmaking을 구축해야 하는 경우, 이러한 상태를 수동으로 관리하려면 webhook 설정, 외부 데이터베이스 스케일링, 서버 간 동기화 처리가 필요합니다.

horizOn을 사용하면 이러한 Backend 관련 문제들이 자동으로 처리됩니다. horizOn SDK를 게임 서버에 통합하면 플레이어 세션 관리를 전용 클라우드 데이터베이스로 오프로드할 수 있습니다. 플레이어의 연결이 끊어질 때 horizOn은 자동으로 세션 정리를 트리거하고, 글로벌 데이터베이스를 업데이트하며, Verse의 256 KB 메모리 제한을 초과하거나 runtime crash를 일으킬 걱정 없이 여러 서버 인스턴스 간에 인벤토리 레코드를 동기화합니다.

UEFN Backend를 확장할 준비가 되셨나요? horizOn을 무료로 사용해 보거나 API docs를 확인해 보세요.

---

Source: When using weak maps, does a player's entry in the map automatically get removed on them leaving the game?