Building Unreal Engine as a Library

Building Unreal Engine as a library that you can control from external applications

Windows
MacOS
Linux

Unreal Engine as a Library (UELibrary) repackages the functionality of Unreal Engine 4 (UE4) into a library, enabling other applications to spawn and control their own UE4 instances. UELibrary provides a simple, platform-agnostic API to drive UE4. UE4 provides the source code to UELibrary along with a sample application, so developers can examine the process and even add their own engine, plugin, or project-level API functions.

Building UELibrary

You can build UELibrary for monolithic editor builds on Win64. UELibrary builds alongside the engine, and will produce its .lib file with a name and path somewhere under /Engine/Intermediate/Build/, according to the build configuration you chose. For example, the Development Editor configuration on Win64 outputs /Engine/Intermediate/Build/Win64/UE4Editor/Development/UELibrary/UE4Editor-UELibrary.dll. To build it as part of a project, you must add the following code to your project's *.Target.cs file:

GlobalDefinitions.Add("UE_LIBRARY_ENABLED=1");
LinkType = TargetLinkType.Monolithic;
bShouldCompileAsDLL = true;

You can interact with UELibrary through the built-in API outlined below, or you can expand the API to suit your application's needs.

Built-In API

The built-in API gives control over four basic features: Starting the engine, passing in Windows messages, ticking the engine, and shutting the engine down.

Exposed Function Signature

Purpose

int UELibrary_Init(HINSTANCE hInst, HWND hWnd, const char* CmdLine)

Starts UE4 with a command line, registering it to the owning application and window you provide. Be sure to include a .uproject file and a map to load in the command line. A non-zero return value indicates an error. You can only call this once per session; running multiple UE4 instances (or rendering to multiple windows) is not supported.

int UELibrary_Tick()

Ticks the engine. We recommend calling this frequently, as most UE4 applications expect to tick 30 to 60 times per second, or more in the case of VR applications. A non-zero return value indicates an error.

The engine will determine the time difference between this tick and the one before it. Calling it infrequently will result in the engine simulating a large period of time in a single tick the next time you call it. The engine has built-in rules like time dilation and maximum delta time for a single tick that you should consider if you plan to call this function infrequently. VR applications or hardware may stop rendering at low tick rates in order to protect users from motion sickness.

LRESULT UELibrary_WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)

Passes Windows messages into the engine. This is a passthrough to WndProc, and returns whatever value WndProc returns.

int UELibrary_Shutdown()

Shuts down UE4. This is permanent; you cannot restart UE4 after shutting it down. A non-zero return value indicates an error.

This simple API is exposed by default, and gives you the tools you need to operate UE4 externally. You can expand the API if you need additional capabilities.

Expanding the API

You can also expand the API to suit your needs, exposing additional existing or new functionality for external use. To do this, you must first modify your project's *.Target.cs file as described above. Write any additional functions your application needs and use the UELIBRARYAPI macro to expose them.

While you might want to implement your new functionality directly in the engine, we advise against this. Use project-level implementations as described.

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss