Unreal Engine 5 Documentation has been moved to the Epic Developer Community

Building Unreal Engine as a Library

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

Choose your operating system:

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.

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 .

Download Unreal Source Code

You can download Unreal Engine from Github after linking your Epic Games account. Refer to Downloading Unreal Engine Source Code for more information. In the example below, we used Github Desktop to clone the Unreal Engine release to our local hard drive.

unreal-on-github-desktop-link

Ensure that you have selected the correct 4.27 branch unreal-engine-branch

Copying the Sample Projects

The sample projects are not part of the github release yet, however the archive is currently available to download here You can extract and copy the provided projects in the Samples/Apps folder.

sample-projects

Editing the UProject Directory File

  1. In your Unreal Engine source root folder, locate the UE4Games.uprojectdirs file and add the following line to include the provided sample projects : 

    Samples/Apps

    sample-apps-directory

  2. Save the file.

Prepare the Engine for Building

  1. Navigate to your Setup.bat and run the script to download the additional prerequisites files.1.

  2. Run the GenerateProjectFiles.bat file.

  3. You can choose to either:

  • Build the UE4.sln . If you choose to open and compile the UE4.sln , then it will build all the engine and it's tools for the target you specified. This may take time to complete.

  • Build the UESampleApp project.

we recommended you open the UELibraryApp.sln which has already been set up with a dependency to the UELibraryProjectEmbeddedEditor .

Adding Starter content

The provided sample app doesn't come with content. To have something to display in the application, you can copy the startup content files located in UnrealEngine\Samples\StarterContent\Content\StarterContent to the content folder of UELibraryProject.

sample-apps-folder-list

Building UELibraryApp

  1. Open the UnrealEngine\Samples\Apps\UELibraryApp\UELibraryApp.sln file and ensure that UELibraryApp is selected.

  2. Set the target as Release/x64 .

    unreal-library-target-build

  3. Build the solution. The build will occur in two steps:

    • The first step will build Unreal Header Tool , the application in charge of parsing all the UE modules files and creating build instructions.

    build-output0window

    • Then the necessary engine modules will be built.

    build-output-window

Running the Application.

You can run the app by pressing F5 from within Visual Studio, or launch the executable UELibraryApp.exe located in your UnrealEngine\Samples\Apps\UELibraryApp\x64\Release directory. The first time you run the application, it may take some time for the shaders to be built, however it is only done once.

If you receive a warning message about a missing map at startup that invites you to load a default map, then this is because you did not add content to the UELibraryProject.

application-runtime-output

Adding your own content

In order to be able to edit the project sample and add your own content, you will first need to build the editor and the project itself. Open the UE4.sln , then define the UELibraryProject as a startup project and build it. If you have already done it once before, you'll be able to open the project by clicking on the uproject file from the Explorer.

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