将虚幻引擎构建为库

将虚幻引擎构建为可以从外部应用程序进行控制的库

Choose your operating system:

Windows

macOS

Linux

本页面的内容

虚幻引擎作为库使用(Unreal Engine as a Library,UELibrary) 会将 虚幻引擎4 的功能重新打包成一个库,以便其他应用程序生成和控制它们自己的UE4实例。UELibrary提供了一种简单、不依赖于平台的API来驱动UE4。UE4提供了UELibrary的源代码以及示例应用,方便开发人员可以查看流程,甚至添加自己的引擎、插件或项目级别API函数。

该功能创建了一个库,其中包括虚幻引擎最终用户许可协议("EULA")中定义的"引擎工具"。请阅读并理解你在EULA中对引擎工具拥有的权利,特别是在发布包含引擎工具的产品时的限制。欲了解详情,请访问我们的FAQ自定义许可页面

构建UELibrary

你可以为Win64平台上的单体编辑器版本构建UELibrary。UELibrary会随着引擎一起构建,并且根据你选择的编译配置,它会生成一个带有名称的 .lib 文件,其路径位于 /Engine/Intermediate/Build/ 下。例如,在Win64平台上,采用开发编辑器(Development Editor)配置时,将会输出 /Engine/Intermediate/Build/Win64/UE4Editor/Development/UELibrary/UE4Editor-UELibrary.dll。要在项目中构建该配置,你必须将以下代码添加到项目的 *.Target.cs 文件中:

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

你可以通过下面介绍的内置API与UELibrary交互,也可以对API进行扩展以满足应用程序的需求。

内置API

内置API提供了四个基本控制功能:启动引擎、传入Windows消息、更新引擎、关闭引擎。

公开的函数签名

目的

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

通过命令行启动UE4,将其注册到上级应用程序和你提供的窗口。请确保在命令行中包含 .uproject 文件以及要加载的地图。非零返回值表示出错。每个会话只能调用此函数一次;不支持运行多个UE4实例(或渲染至多个窗口)。

int UELibrary_Tick()

更新函数。我们建议经常调用此函数,因为大部分UE4应用程序每秒更新30到60次,如果是VR应用,更新频率会更高。非零返回值表示出错。

引擎会确定两次Tick之间的时间差。假如不频繁调它,会导致在单次Tick期间,引擎模拟了大量 用更新函数将导致在下次调用它时使引擎在单次更新函数中模拟一大段时间。引擎具有内置的规则,例如单次更新函数的时间膨胀和最大增量时间,如果你计划不频繁调用此函数,则需要考虑这些规则。为防止用户产生晕动症,VR应用程序或硬件可能会以较低的更新速度来停止渲染。

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

将Windows消息传递到引擎。这是针对 WndProc 的直通(passthrough),并将返回 WndProc 所返回的值。

int UELibrary_Shutdown()

关闭UE4。该操作是永久性的,你无法在关闭UE4之后重新启动它。非零返回值表示出错。

这是默认公开的简单API,为你提供在外部操作UE4所需的工具。如果你需要其他功能,可以对API进行扩展。

扩展API

你还可以扩展API来满足你的需求,暴露其他现有函数或新函数,以供外部使用。要实现此目标,你必须首先根据上文介绍修改项目的 *.Target.cs 文件。编写应用程序所需的其他函数,并使用 UELIBRARYAPI 宏暴露它们。

虽然你可能希望直接在引擎中实现新功能,但我们不建议这么做。请按照文中所述的项目级实现方法进行操作。

本文基于此前的虚幻引擎版本编写,未针对当前的虚幻引擎5.0版本更新过。