Unity Addressables 동적 에셋 관리 시 AsyncOperationHandle 누수로 인한 씬 전환 메모리 해제 실패 분석과 참조 카운팅 최적화

🌐 English Abstract

This technical deep-dive addresses memory leak issues caused by unreleased AsyncOperationHandle instances during scene transitions in Unity's Addressable Asset System. It explains the mechanics of underlying AssetBundle reference counting and pinpoints edge cases where async handles remain dangling after scene unloads. Furthermore, it provides robust architectural patterns, C# code implementations, and profiling techniques to automate handle lifecycle management and optimize total memory footprint.

유니티(Unity) 프로젝트가 대형화되고 동적 리소스 로딩 방식이 단순 Resources 폴더 방식에서 어드레서블 에셋 시스템(Addressable Asset System)으로 세대교체가 이뤄지면서, 메모리 관리의 주도권은 엔진 내부에서 개발자의 코드로 이동했습니다. 그러나 어드레서블을 도입한 많은 프로젝트가 개발 중반 이후 공통적으로 직면하는 치명적인 문제가 있습니다. 바로 씬 전환(Scene Transition) 시 발생하는 불완전한 메모리 해제 및 에셋 번들(AssetBundle) 누수 현상입니다.

기존 `Resources.UnloadUnusedAssets()`나 씬 전환 시의 자동 GC(Garbage Collection)에 의존하던 수동적 메모리 관리 방식은 어드레서블의 참조 카운팅(Reference Counting) 구조와 충돌을 일으킵니다. 특히 `AsyncOperationHandle`을 정확히 해제하지 않으면 씬이 언로드되어도 에셋 번들이 램(RAM) 및 VRAM에 영구히 상주하게 됩니다. 본 포스팅에서는 이러한 트러블슈팅 사례를 바탕으로 근본적인 원인을 분석하고 구조적 해결책을 제시합니다.

1. Addressables 참조 카운팅(Reference Counting) 동작 메커니즘

어드레서블 시스템의 핵심은 내부적인 참조 카운트(Reference Count) 관리입니다. 에셋이나 씬, 번들을 로드할 때마다 해당 리소스의 참조 카운트가 1씩 증가하고, 명시적으로 해제(Release)를 호출할 때 1씩 감소합니다. 이 카운트가 정확히 0에 도달해야만 실제 AssetBundle.Unload(true)가 호출되어 메모리에서 제거됩니다.

AsyncOperationHandle의 역할과 수명 주기(Lifecycle)

`Addressables.LoadAssetAsync()` 또는 `Addressables.InstantiateAsync()`를 호출하면 유니티는 내부 작업 상태를 추적하는 `AsyncOperationHandle` 또는 `AsyncOperationHandle` 구조체(Struct)를 반환합니다. 이 핸들은 단순한 데이터 래퍼가 아니라, 내부 C++ 에셋 번들 메모리 포인터의 참조 카운트를 유지하는 열쇠 역할을 합니다.

• Addressables.Release(handle): 해당 핸들이 가리키는 에셋의 참조 카운트를 1 감소시킵니다. 카운트가 0이 되면 에셋 및 포함된 번들이 메모리에서 언로드됩니다.
• Addressables.ReleaseInstance(gameObject): `InstantiateAsync`로 생성된 게임 오브젝트 인스턴스를 파괴(Destroy)함과 동시에 내부 핸들의 참조 카운트를 감소시킵니다.

문제는 `AsyncOperationHandle`이 값 타입(Value Type Struct)이라는 점입니다. 여러 클래스나 변수 수식어로 복사되어 전달될 수 있지만, 최종적으로 해제 함수에 전달되어야 하는 것은 최초에 로드되어 카운트를 증가시킨 동일한 내부 작업 상태(AsyncOperationImpl)입니다. 만약 C# 스크립트가 파괴되면서 이 핸들을 잃어버리거나(Orphaned Handle) 해제하지 않으면, 에셋 번들의 참조 카운트는 1로 고정되어 영구적인 메모리 누수(Memory Leak)가 발생합니다.

2. 씬 전환 시 발생 빈도가 높은 엣지 케이스(Edge Cases) 분석

단순히 `OnDestroy()`에서 `Release()`를 부르는 것만으로는 모든 메모리 누수를 막을 수 없습니다. 실무 개발 환경에서 빈번하게 발생하는 엣지 케이스는 다음과 같습니다.

케이스 A: 비동기 로딩 미완료 상태에서 씬 전환 (Interrupted Async Operation)

에셋 로딩(`LoadAssetAsync`)을 요청한 직후, 로딩이 완료되기 전에 유저가 씬을 전환하거나 다른 씬으로 이탈하는 경우입니다. 비동기 작업(Task 또는 Coroutine)이 완료되지 않은 상태에서 씬이 언로드되면, 완료 콜백(`Completed`)이 호출되지 않거나 콜백 내부에서 참조하려던 객체가 이미 `Null` 상태가 되어 해제 로직이 유실됩니다.

케이스 B: InstantiateAsync 호출 후 Destroy()를 유니티 기본 함수로 호출

`Addressables.InstantiateAsync()`로 생성한 Prefab 인스턴스를 파괴할 때 `UnityEngine.Object.Destroy(gameObject)`를 사용하는 실수입니다. 유니티의 기본 `Destroy()`는 C# 및 C++ 엔진 레벨의 프리 게임오브젝트만 제거할 뿐, 어드레서블의 참조 카운터를 감소시키지 않습니다. 이로 인해 씬에 오브젝트는 사라졌지만 memory 상에 에셋 번들이 그대로 남아있는 현상이 발생합니다.

케이스 C: 종속 에셋(Dependencies)의 꼬임 현상

A 씬에서 로드한 UI 텍스처가 B 씬의 3D 모델 머티리얼과 동일한 에셋 번들에 묶여있는 경우입니다. A 씬이 종료될 때 핸들을 해제하지 않으면, B 씬이 종료되고 B 에셋을 해제하더라도 공통 번들의 참조 카운트가 0이 되지 않아 메모리가 지속적으로 누적됩니다.

3. 실무 트러블슈팅: 메모리 누수 방지 코드 아키텍처

이러한 문제를 해결하기 위해 1) 비동기 취소 토큰(CancellationToken)의 동기화, 2) 핸들 추적 자동화 래퍼(Wrapper) 패턴, 3) MonoBehavior 수명 주기 연동(Auto-Release Agent)을 구현해야 합니다.

안전한 비동기 로딩 및 자동 해제 컴포넌트 구현

아래 코드는 GameObject의 `OnDestroy` 타임밍과 `CancellationToken`을 결합하여, 로딩 도중 씬이 전환되거나 객체가 파괴되더라도 핸들이 미해제되는 일을 완벽히 방지하는 프로덕션 레벨의 C# 패턴입니다.

using System;
using System.Threading;
using Cysharp.Threading.Tasks; // UniTask 활용 추천
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class AddressableAssetLoader : MonoBehaviour
{
    private AsyncOperationHandle _handle;
    private bool _isLoaded = false;

    /// <summary>
    /// 안전하게 에셋을 로드하고 게임 오브젝트의 수명 주기에 바인딩합니다.
    /// </summary>
    public async UniTaskVoid LoadAssetSafe<T>(AssetReferenceT<T> assetReference, Action<T> onComplete) where T : UnityEngine.Object
    {
        CancellationToken cancellationToken = this.GetCancellationTokenOnDestroy();

        try
        {
            // 비동기 작업 시작 및 핸들 저장
            _handle = assetReference.LoadAssetAsync();

            // Task 대기 중 씬 전환 등으로 인해 GameObject가 Destroy되면 CancellationException 발생
            T result = await _handle.ToUniTask(cancellationToken: cancellationToken);

            if (_handle.Status == AsyncOperationStatus.Succeeded)
            {
                _isLoaded = true;
                onComplete?.Invoke(result);
            }
        }
        catch (OperationCanceledException)
        {
            // 씬 전환 등으로 로딩 도중 객체가 파괴된 경우 처리
            Debug.LogWarning($"[Addressables] Loading canceled for {assetReference.RuntimeKey}. Releasing handle.");
            ReleaseHandle();
        }
        catch (Exception ex)
        {
            Debug.LogError($"[Addressables] Failed to load asset: {ex.Message}");
            ReleaseHandle();
        }
    }

    private void ReleaseHandle()
    {
        if (_handle.IsValid())
        {
            Addressables.Release(_handle);
            _isLoaded = false;
            Debug.Log("[Addressables] Handle successfully released.");
        }
    }

    private void OnDestroy()
    {
        // 이미 완료된 로드에 대한 핸들 해제
        ReleaseHandle();
    }
}

씬 전환 시 전역 핸들 트래킹 매니저 (Addressable Tracker Manager)

개별 스크립트 외에도 씬 단위로 호출된 모든 `AsyncOperationHandle`을 중앙에서 등록하고, 씬 전환 이벤트(`SceneManager.sceneUnloaded`) 발생 시 미해제된 핸들을 전수 조사하여 강제 해제하는 안전장치(Safety Net) 아키텍처가 필요합니다.

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using UnityEngine.SceneManagement;

public class AddressableSceneScopeManager : MonoBehaviour
{
    private readonly List<AsyncOperationHandle> _trackedHandles = new List<AsyncOperationHandle>();

    private void Awake()
    {
        SceneManager.sceneUnloaded += OnSceneUnloaded;
    }

    public void TrackHandle(AsyncOperationHandle handle)
    {
        if (handle.IsValid())
        {
            _trackedHandles.Add(handle);
        }
    }

    private void OnSceneUnloaded(Scene current)
    {
        // 씬 전환 시 누수된 모든 핸들 일괄 Release
        foreach (var handle in _trackedHandles)
        {
            if (handle.IsValid())
            {
                Addressables.Release(handle);
            }
        }
        _trackedHandles.Clear();
        SceneManager.sceneUnloaded -= OnSceneUnloaded;
    }
}

4. Addressables Profiler & Event Viewer를 활용한 디버깅 및 분석

코드 작성 후 실제 메모리에서 에셋 번들이 정확하게 해제되고 있는지 검증하려면 유니티 내장 툴인 Addressables Event Viewer를 활용해야 합니다.

설정 및 모니터링 방법:

1. `Window` > `Asset Management` > `Addressables` > `Event Viewer` 메뉴를 엽니다.
2. Addressables System Settings에서 Send Profiler Events 항목을 활성화(Check)합니다.
3. 게임 플레이 모드 진입 후 씬 전환을 수행합니다.

💡 Event Viewer 그래프 읽는 법:
- 녹색 그래프(Ref Count): 특정 에셋 번들의 참조 카운트를 나타냅니다. 씬이 파괴되었음에도 녹색 그래프가 0으로 떨어지지 않고 평행선을 유지한다면 해당 씬에 AsyncOperationHandle 누수가 존재하는 것입니다.
- 분홍색/붉은색 블록: 메모리에 상주하는 실제 에셋 데이터입니다. 참조 카운트가 0이 되는 즉시 해당 블록이 화면에서 사라져야 정상입니다.

5. 최종 요약 및 프로덕션 환경 권장 가이드

Unity Addressables 기반의 동적 에셋 관리 시스템을 안정적으로 운용하기 위해서는 다음 원칙을 개발 표준으로 정의해야 합니다.

• InstantiateAsync 사용 시 단짝 규칙: `InstantiateAsync`로 만든 객체는 절대로 일반 `Destroy()`로 지우지 말고, 반드시 `Addressables.ReleaseInstance()`를 통해서만 파괴합니다.
• CancellationToken 필수 적용: 비동기 로딩 메서드는 씬 전환 시 로딩 프로세스를 즉시 취소할 수 있도록 UniTask의 `GetCancellationTokenOnDestroy()` 또는 C#의 `CancellationToken`을 연결합니다.
• 에셋 번들 분리 최적화: 씬 단위로 완전히 수명 주기가 나누어지는 에셋들은 동일한 에셋 번들 그룹에 묶이지 않도록 어드레서블 그룹(Addressable Groups) 설정을 세분화합니다. 묶여있는 에셋 중 하나라도 참조 카운트가 1이면 전체 번들이 메모리에 남기 때문입니다.
• 정기적인 Memory Profiler 캡처: 씬 전환 전/후의 메모리 스냅샷(Snapshot)을 찍어 Native Memory Object 항목에 Unloaded 되지 않은 `AssetBundleData`가 잔존하는지 지속적으로 감사(Audit)해야 합니다.

에셋 번들의 참조 카운팅 라이프사이클을 엄격하게 관리하는 아키텍처를 도입하면 씬 전환 시 발생하는 원인 불명의 크래시(OOM - Out Of Memory)와 메모리 핑퐁 현상을 완벽히 해결할 수 있습니다.