플러그인 호환 작업을 하며 언리얼 엔진에 기여한 경험

서론 

그저 이전에 제작한 플러그인의 UE 5.7 버전 지원을 원했을 뿐이다.
 
작업을 이어가다 보니 언리얼 엔진의 코드에 기여하게 됐다.

 
뭔가 거창한 그런 기여는 아니고, 단 13글자 짜리의 간단한 변경이다.

 
아주 간단한 변경 사항이었지만, 이 덕분에 Audio Tracing 플러그인은 UE 5.7 버전을 지원할 수 있게 되었다.
 

---

기여하게 된 배경 

간단한 배경 지식 

Audio Tracing은 실시간 Ray Traced Audio를 제공하는 플러그인으로, 실시간 음향 전파 시뮬레이션을 위해 하드웨어 레이 트레이싱을 사용한다.
그리고 언리얼 엔진 5의 Lumen은 하드웨어 레이 트레이싱도 사용하므로, 이를 위한 가속 구조(TLAS)를 빌드한다.
안정성과 효율을 위해, Audio Tracing은 이 Lumen 하드웨어 레이 트레이싱(Lumen HWRT) 가속 구조를 재활용하여, 음향 전파 시뮬레이션을 진행한다.
 
더 자세한 정보는 다음 링크의 글에서 확인할 수 있다.
https://mstone8370.tistory.com/50

[UE5 | Audio Tracing] 개요

 

발생한 문제 

엔진에서 빌드한 Lumen HWRT의 TLAS를 활용해야 하므로, Renderer 모듈을 통해 TLAS를 받아와야 한다.
그런데 UE 5.7 버전으로 올라오면서 Renderer 모듈이 일부 변경되었고, 여기에서 문제가 발생했다.
 

5.7 버전부터, TLAS를 리턴하는 함수는 FViewHandle이라는 새로운 정보를 요구한다.

이와 함께, 현재의 View를 통해서 FViewHandle을 받아오는 함수도 추가되었다.

 
이 두 함수는 Renderer 모듈의 API에 포함되어, Renderer 모듈의 외부(e.g. 게임, 플러그인)에서 사용할 수 있다.

문제는, FViewHandle을 리턴하는 함수는 inline 함수이며, 구현에서 API에 포함되지 않은 함수를 호출하고 있다는 점이다.

// Source/Runtime/Renderer/Private/RayTracing/RayTracingScene.h

class FRayTracingScene
{
public:
    // 하드웨어 레이 트레이싱 가속 구조(TLAS)를 리턴하는 함수.
    // RENDERER_API 매크로를 통해 외부 모듈에서 사용 가능.
    RENDERER_API FRDGBufferSRVRef GetLayerView(ERayTracingSceneLayer Layer, FViewHandle ViewHandle) const;
    
    // ...
}



// Source/Runtime/Renderer/Private/SceneRendering.h

class FViewInfo : public FSceneView
{
public:
    // 위의 GetLayerView() 함수에 전달할 FViewHandle을 획득하기 위한 함수.
    // 구현이 헤더 파일에 있는 inline 함수로, 외부 모듈에서 함수 사용 가능.
    inline const FRayTracingScene::FViewHandle& GetRayTracingSceneViewHandle() const
    {
        if (UNLIKELY(IStereoRendering::IsStereoEyePass(StereoPass) && IStereoRendering::IsASecondaryPass(StereoPass)))
        {
            // 구현에서 내부 멤버 함수인 GetPrimaryView() 함수 호출
            return GetPrimaryView()->RayTracingSceneViewHandle;
        }

        return RayTracingSceneViewHandle;
    }

    // 이 함수는 외부 모듈에서 사용 불가능. ( RENDERER_API 매크로 X, inline 함수 X )
    const FViewInfo* GetPrimaryView() const;
    
    // ...
}

 

그 결과, 외부 모듈에서는 FViewInfo::GetPrimaryView()의 구현을 모르므로, 호출하면 컴파일 시 링크 에러(LNK2019, LNK2001)가 발생한다.

따라서, TLAS를 획득할 수 없게 되었고, Audio Tracing 플러그인의 UE 5.7 지원이 불가능하게 되었다.
 
외부 모듈 사용을 전제로 한 API가 내부 구현에 의존하고 있으므로, API 설계의 오류임은 확실했다.
 

---

문제 해결 방법 

문제 해결 방법은 아주 간단하다.

FViewInfo::GetPrimaryView() 함수도 Renderer API에 포함시키면 문제가 해결된다.

const FViewInfo* GetPrimaryView() const;

                  ↓

RENDERER_API const FViewInfo* GetPrimaryView() const;

 
엔진을 소스 코드로 빌드해서 이 방법으로 문제를 해결할 수 있는 걸 확인했다.
 
대신 엔진 코드를 수정해야 하므로, Fab에 제출할 수 없다는 문제가 발생한다.
따라서, 다음 핫픽스에 이 문제가 수정된다면, 그제서야 5.7 버전의 지원이 가능해진다.
 
나는 이 문제를 빠르게 해결하길 원했기에, 다른 누군가가 해결해 주길 기다리는 대신에 적극적으로 해결하고자 했다.
따라서, 가장 직접적인 방법인 Github를 통한 PR을 보내는 방법을 선택했다.
 

Github에 PR 보내기 

방법은 공식 문서에도 잘 설명되어 있으니 참고하여 진행했다.
https://dev.epicgames.com/documentation/ko-kr/unreal-engine/contributing-to-the-unreal-engine

언리얼 엔진에 기여 | 언리얼 엔진 5.7 문서 | Epic Developer Community

 
그렇게 제출한 [PR #14064].
 
기본적인 조건만 통과되면 UnrealBot이 자동으로 Tracked 라벨을 달아준다.

 
PR을 보내기 위해 fork 했던 리포지토리가 지워지면 PR이 닫히게 되니 주의해야 한다.

Epic과 Github 계정 연동 설정을 건드리다가 연동이 풀리면서 fork 했던 게 지워졌다...
 

---

결과 

급하게 다시 fork 하고 PR을 다시 보내긴 했지만, 내부에서는 이미 트래킹 되어서 계속 처리 중이었나 보다.
닫힌 PR이었지만, 이후 다시 보니 이렇게 여러 브랜치에 반영되었다.

 
그리고 2026년 1월, 핫픽스 버전인 5.7.2가 릴리즈 되면서 이 PR도 담기게 되었다.
https://forums.unrealengine.com/t/5-7-2-hotfix-released/2693914

5.7.2 Hotfix Released

관련 포럼 글에서 해당 Jira issue ID를 검색하면 찾을 수 있다.

 
그리고 덕분에, Audio Tracing은 UE 5.7 버전을 지원할 수 있게 되었다.

 
플러그인을 위해 엔진을 바꾸는 과정은 성공적으로 마무리 되었다.
 

---

이후 계획 

이번 기여는 수정 내용 자체는 아주 간단하고, 발생할 수 있는 side effect가 매우 적었기 때문에 수월하게 반영될 수 있었다고 생각한다.
 
그리고, 현재 상황에서 엔진에 기여하고 싶은 것이 하나 더 있긴 하다.
플러그인 제작 과정에서 어려움을 겪었고, 다른 사람들도 이러한 어려움을 겪을 수 있다고 생각한 시스템이 있었다.
여기에 개선 가능성이 충분히 있다고 생각한다.
하지만, 로직이 꽤나 복잡하게 얽혀있고, side effect가 쉽게 발생할 위험성도 있어서 잘 해결될지는 모르겠다.