Unreal Engine as a Library (UELibrary) repackages the functionality of Unreal Engine (UE) into a library, enabling other applications to spawn and control their own UE5 instances. UELibrary provides a simple, platform-agnostic API to drive UE5. UE5 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.
This feature creates a library that includes "Engine Tools" as defined in the Unreal Engine End User License Agreement ("EULA"). Please read and understand your rights with respect to Engine Tools under the EULA, in particular, the limitations to distributing products that contain Engine Tools. For more information, visit our FAQ and Custom License Page.
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/UnrealEditor/Development/UELibrary/UnrealEditor-UELibrary.lib. 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 UE5 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 UE5 instances (or rendering to multiple windows) is not supported. |
int UELibrary_Tick() |
Ticks the Engine. We recommend calling this frequently, as most UE5 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 UE5. This is permanent; you cannot restart UE5 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 UE5 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.