라이브러리형 언리얼 엔진 (Unreal Engine as a Library, UELibrary)은 언리얼 엔진(UE) 의 기능을 하나의 라이브러리로 리패키징하여, 다른 애플리케이션이 UE5 인스턴스를 생성 및 제어할 수 있도록 합니다. UELibrary는 UE5를 실행할 수 있는 단순하고 플랫폼 제한이 없는 API를 제공합니다. UE5는 샘플 애플리케이션과 함께 UELibrary에 소스 코드를 제공하여 개발자가 프로세스를 검사하고, 심지어 자신의 엔진, 플러그인, 혹은 프로젝트 레벨의 API 함수를 추가할 수 있도록 합니다.
이 기능을 사용하면 언리얼 엔진 최종 사용자 라이선스 계약 (End User License Agreement, 'EULA')에서 정의하는 '엔진 툴'이 포함된 라이브러리가 생성됩니다. EULA에 기록된 엔진 툴 관련 권리 조항, 특히 엔진 툴을 포함한 배포용 제품에 대한 제약 조항을 자세히 읽어보세요. 자세한 정보를 확인하려면 에픽게임즈의 FAQ 및 맞춤형 라이선스 페이지를 방문하세요.
UELibrary 빌드하기
Win64의 모놀리식 에디터 빌드에 UELibrary를 빌드할 수 있습니다. UELibrary는 엔진에 맞게 빌드되며, 선택한 빌드 환경설정에 따라 /Engine/Intermediate/Build/ 내에 이름 및 패스 정보가 포함된 .lib 파일을 생성합니다. 예를 들어 Win64에 개발 에디터(Development Editor) 환경설정을 만들면 /Engine/Intermediate/Build/Win64/UnrealEditor/Development/UELibrary/UnrealEditor-UELibrary.lib 파일이 생성됩니다. 프로젝트에 이 환경설정을 빌드하려면 프로젝트의 *.Target.cs 파일에 다음 행을 추가해야 합니다.
GlobalDefinitions.Add("UE_LIBRARY_ENABLED=1");
LinkType = TargetLinkType.Monolithic;
bShouldCompileAsDLL = true;
아래에서 강조한 내장 API를 통해 UELibrary와 상호작용하거나, 어플리케이션의 필요에 따라 API를 확장할 수 있습니다.
내장 API
내장 API를 통해 엔진 실행, Windows 메시지 전달, 엔진 티킹, 엔진 종료 이렇게 4가지 기본 기능을 제어할 수 있습니다.
| 노출된 함수 시그니처 | 목적 |
|---|---|
int UELibrary_Init(HINSTANCE hInst, HWND hWnd, const char* CmdLine) |
명령줄로 UE5를 시작하고 자신의 애플리케이션과 창에 등록합니다. 명령줄에 .uproject 파일과 로드할 맵을 꼭 포함하세요. 0이 아닌 반환 값은 오류를 나타냅니다. 이 함수는 세션마다 한 번만 호출할 수 있습니다. 다수의 UE5 인스턴스를 실행하거나 다수의 창에 렌더링하는 기능은 지원되지 않습니다. |
int UELibrary_Tick() |
엔진에 틱을 적용합니다. 대부분 UE5 애플리케이션이 틱을 1초에 30~60번, VR 애플리케이션은 훨씬 빠르게 업데이트하므로 이 함수를 자주 호출하면 도움이 됩니다. 0이 아닌 반환 값은 오류를 나타냅니다. 엔진은 이전 틱과 현재 틱 사이의 시차를 결정합니다. 틱을 자주 호출하지 않으면 다음번에 호출하는 시간까지의 긴 기간을 하나의 틱으로 시뮬레이션합니다. 엔진에는 시간 지연, 최대 델타 시간 등 한 번의 틱에 내장 규칙이 적용됩니다. 이 함수를 자주 호출하지 않을 경우 이러한 규칙을 고려해야 합니다. VR 애플리케이션 또는 하드웨어는 틱 속도가 너무 낮을 경우, 사용자의 멀미를 방지하기 위해 렌더링을 멈추기도 합니다. |
LRESULT UELibrary_WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) |
Windows 메시지를 엔진에 전달합니다. 이 함수는 WndProc 를 통과하며, WndProc 에서 반환하는 값을 반환합니다. |
int UELibrary_Shutdown() |
UE5를 종료합니다. 이 함수는 영구적이므로 UE5를 종료한 뒤 재시작할 수 없습니다. 0이 아닌 반환 값은 오류를 나타냅니다. |
이 간단한 API는 기본적으로 노출되어 UE5를 외부에서 운용하는 데 필요한 툴을 제공합니다. 추가 기능이 필요하면 API를 확장할 수 있습니다.
API 확장하기
필요에 따라 API를 확장할 수 있으며, 외부 사용을 위해 추가적인 기존 기능 또는 신규 기능을 노출할 수 있습니다. 이를 위해서는 위에서 설명한 대로 프로젝트의 *.Target.cs 파일부터 수정해야 합니다. 애플리케이션에서 필요로 하는 함수를 추가로 작성한 뒤 UELIBRARYAPI 매크로로 노출할 수 있습니다.
엔진에서 새 함수를 직접 구현하고 싶다면 이 기능을 사용하지 마세요. 앞서 설명한 프로젝트 레벨 구현을 사용하세요.