插件

如何创建虚幻引擎插件。

Windows
MacOS
Linux

本页介绍如何开发自己的插件,以便配合虚幻引擎工具和运行时间使用和。

许多虚幻引擎子系统都设计为可扩展,无需修改引擎代码, 可直接添加全新的功能,及修改内置的功能。您可以创建新文件类型,添加新菜单项目和工具栏命 令至编辑器,甚至可以添加全新的功能和编辑器子模式!

如需直入正题,并马上试用插件,请参阅插件示例部分。

插件编辑器用户界面

您可以打开 编辑(Edit) 菜单的 插件(Plugin) 编辑界面查看当前已安装的插件。

PluginsEditor.png

您可从主“窗口(Window)”菜单访问插件编辑器。此界面显示当前已安装的所有插件, 并且可逐项启用或禁用。

您可以使用左侧的树形界面浏览插件类别。选择一个类别就会显示该类别的所有插件, 及其任意子类别中的插件。浏览类别时,UI 顶部显示的“面包屑” 痕迹可以快速跳转至上一级的类别。类别名称旁 显示的数字表示该类别可用的插件数量。

PluginCategories.png

插件显示在主列表中,与插件一起显示的还有插件的名称、图标、 当前版本、有效描述、作者(及可选的网页超链接)及当前是否启用。

可以使用顶部的搜索功能按钮按名称搜索列表中显示的插件。

SearchingPlugins.png

切换插件描述下的 启用(Enable) 复选框即可启用或禁用插件, 以便配合当前活跃的项目使用。可能需要重启编辑器,所做更改才会生效。

插件剖析

有代码的插件将有源文件夹。该文件夹包含一个或多个含该插件模块源 代码的目录。请注意,插件通常都有代码,但并非一定要有代码。请参阅插件的代码 部分了解更多信息。

包含代码模块的插件将有自己的二进制文件夹,该文件夹包含该插件的已编译代码。 另外,临时构建的产品文件将保存在插件目录下的中间文件夹。

插件可拥有包含其特有的资源文件的自有内容文件夹。请参阅插件中的内容 部分了解更多信息。

插件暂不支持配置文件。我们正考虑日后添加此功能。

另外,插件暂不支持各自的派生数据缓存分配。我们正考虑 日后添加此功能。

插件文件夹

插件始终位于插件目录中。为了方便查找,插件必须位于 虚幻引擎上适用于插件的有效搜索路径上。

插件类型

搜索路径

引擎(Engine)

/UE4 Root/Engine/Plugins/My Engine Plugin/

游戏(Game)

/My Project/Plugins/My Game Plugin/

您也可将插件安排在基础插件文件夹下的子目录中。引擎将扫描待加载插件 的基础插件文件夹下的全部子文件夹,找到插件后不再扫描下方的子目录。

虚幻引擎通过搜索磁盘上的.uplugin查找插件。我们将这些文件称之为插件描述符。它们都是文本文件, 介绍插件的基本信息。每当这些程序运行时,虚幻引擎、虚幻编辑器和虚幻构建工具 都会自动查找并加载插件描述符。请参阅插件描述符中的相关内容, 了解如何创建和自定义这些文件。

插件中的代码

为Visual Studio或Xcode生成项目文件时,任何带源文件夹(含*.Build.cs 文件)的插件都将添加至 项目文件,以便导航至各自的源代码。编译游戏项目时, 虚幻构建工具将自动编译这些插件。

插件可拥有任意数量的模块源目录。大部分插件只包含一个模块,但可以 创建多个模块,例如,需要设计为仅编辑器可以编译的部分功能,以及 仅在游戏运行时才需要的其他代码。

大多数情况下,插件源文件布局与虚幻引擎中的任意其他C++模块一样。

插件可以在模块代码文件夹中类子目录的标头文件中表明新Uobject类型(UCLASS、USTRUCT 等) 。虚幻引擎编译系统将检测这些文件并视需要生成代码,用以支持这些UObject。您将需要按照在C++模块中使用Uobject的一般规则操作, 如在模块源文件中包含生成 的标头文件和模块的已生成 .inl 文件。

插件模块中有一点不同,就是要包含公共源文件标头。大部分插件模块的公共源文件夹中的标头文件没有业务导出 公共 API,因为它们永远不会对引擎或游戏代码建立 直接依赖性(静态链接)。所以,您的公共源文件夹通常是空的。但也有几种例外情况:

  • 如果插件包含多个C++模块,公共文件夹中的代码可在插件内的模块之间共享。

  • 如果您创建的是游戏插件(而非引擎插件),而且您需要允许游戏静态链接其中一个插件 模块。这与插件的概念有些不符,但通常对需要声明游戏类可以直接从中传递或 使用的新Uobject类型的插件有用。引擎本身对此插件没有依赖性,但游戏项目代码和内容 可能对插件有非常大的直接依赖性。

  • 如需使用插件分配公共界面标头,以允许游戏代码或其他插件访问 该插件模块中实施的类型。这种情况较罕见,通常不鼓励这样做,因为我们目 前不打算支持直接依赖其他插件的插件。

插件中的内容

虚幻引擎支持包含内容及二进制代码的插件。如需使用插件中的内容,必须将插件描述符中的“可 包含内容(CanContainContent)”设置设为“(true)”。

游戏项目中的插件

插件位于游戏项目目录下的插件子文件夹中,游戏引擎和编辑器会在启动时检测和加载插件。

如果插件包含带源文件夹(及*.Build.cs文件)的模块,插件代码将自动添加至生成的C++项目文件, 以便您可以在编译游戏项目的同时轻松开发插件。无论何时编译游戏项目, 任何有源代码可用的插件也将编译为对游戏有合成依赖性。

没有源代码子文件夹的插件将被项目生成器忽略,且不会出现在C++项目文件中,但 只要二进制文件存在,游戏启动时将加载这些插件。

引擎插件

虚幻引擎4有一些内置插件位于引擎目录下。引擎插件就像游戏项目中的插件, 但不同的是,引擎插件适用于所有游戏项目。通常,这些插件由引擎和工具程序员创建, 以插件方式提供基本功能。这可让用户无需修改任何引擎代码便可删除或覆盖整个引擎功能。

默认情况下,在加载任意游戏模块或游戏项目插件之前加载引擎插件。

引擎插件有个特殊要求:引擎代码模块不能针对引擎插件模块库创建静态链接。 即引擎插件必须与引擎本身分离,插件模块绝不可成为对引擎模块“有依赖性的模块”。 这种互不依赖的状态能够让引擎在没有插件可供加载时也能正常运行。

分配插件

插件分配需按以下步骤操作.

  1. 确保 .uplugin 文件中的模块列表中加入白名单和黑名单的平台没有错误。

  2. 在编辑器插件浏览器中找到您的插件,并单击“编辑(Edit)……”链接以更新与插件相关的元数据 (描述、文档链接等)。

  3. 单击“**打包(Package)……*”链接可将插件打包至插件分配文件夹。

默认情况下,仅源代码、二进制文件和内容会随着插件一起打包。如需添加其他文件进行打包, 请在插件文件夹下创建一个文件,命名为 Config/FilterPlugin.ini,就可以将此文件置于补充打包路径上,如下:

[FilterPlugin]
/ThirdParty/...
/MyOtherFolder/...

重要事项:

  • 对于含内容的插件,您可能需要生成派生数据以便将内容包含在插件中,以免 要求终端用户生成此数据。此功能暂不可用,不过日后会添加。敬请关注!

  • 暂不支持将 EULA 或其他文档加入待分配的插件。我们可能于日后提供此支持。

插件描述符文件

插件描述符文件的扩展名通常以 .uplugin 结尾。文件名的第一部分即为插件名称。 插件描述文件始终位于插件目录下,引擎会在启动时检测到这些文件。

插件描述符的文件格式为Json(对象表示法(JavaScript Object Notation))。

描述符文件示例

此插件描述符示例来自于上文 UObjectPlugin 示例

{
    "FileVersion" : 3,
    "Version" : 1,
    "VersionName" : "1.0",
    "FriendlyName" : "UObject Example Plugin",
    "Description" : “声明自带的Uobject类型的插件示例。可用作创建自有插件的起始点。",
    "Category" : "Examples",
    "CreatedBy" : "Epic Games, Inc.",
    "CreatedByURL" : "http://epicgames.com",
    "DocsURL" : "",
    "MarketplaceURL" : "",
    "SupportURL" : "",
    "EnabledByDefault" : true,
    "CanContainContent" : false,
    "IsBetaVersion" : false,
    "Installed" : false,
    "Modules" :
    [
        {
            "Name" : "UObjectPlugin",
            "Type" : "Developer",
            "LoadingPhase" : "Default"
        }
    ]
}

描述符文件格式

域名

信息

描述

FileVersion

Required

此插件描述符文件自己的版本。用于与添加至插件系统的新功能后向兼容。您应经常将此设为现在所用引擎版本所允许的最新版本。最新版本目前是 3,但这是指此处已记录的格式的版本。我们预计此版本不会频繁变更。在源代码中,您可以查看 EProjectDescriptorVersion 了解实际值。如需与旧版引擎最大程度兼容,可使用旧版格式,但不推荐这种做法。

Version

Optional

此版本插件的当前版本编号。此值会随着以后版本的推出而增加。此版本编号通常对终端用户不可见。

VersionName

Optional

编辑器UI中显示的插件版本。它从不用于进行任何版本检查,所以无论任何格式都可以,但我们建议使用简单的、 Major.Minor格式。每逢版本编号增加,就要更新此版本名称。

FriendlyName

Optional

编辑器UI中显示的插件名称。如未指定,名称将默认为 .uplugin 文件名。

Description

Optional

一段用于描述该插件用途的文本,也将在编辑器插件窗口中显示。

Category

Optional

这是一种特殊的用点隔开的路径字符串,用来将您的插件分配至编辑器UI中的类别。它纯粹是为了组织结构而设。以 "Editor Features.Level Editing.Mesh Painting" 这一类别路径为例。每个类别都用句号隔开,且代表树中更深的层级。

CreatedBy

Optional

创建此插件的个人或公司名称。可能显示在插件UI中,也可能在其他位置显示。

CreatedBy

Optional

创建此插件的个人或公司的网页链接。若指定,编辑器UI可能显示供用户浏览此网页的超链接。

DocsURL

Optional

插件文档网页链接。若指定,编辑器的插件浏览器可能显示供用户浏览此网页的超链接。

MarketplaceURL

Optional

该插件市场页面的链接。若指定,编辑器的插件浏览器可能显示供用户浏览此网页的超链接。

SupportURL

Optional

该插件支持页面的链接。若指定,将在编辑器插件浏览器上显示。

EnabledByDefault

Optional

如果设为(true),则将在该插件存在时,默认启用该插件。

CanContainContent

Optional

对此有规定,并设为 true 时,启用该插件的内容支持。默认设置为 false。请参阅插件中的内容了解更多信息。

IsBetaVersion

Optional

将其内容标记为测试版本。在插件列表中,“版本(Version)”将被“测试版本(BETA Version)”代替。

Installed

Optional

如果设为“true”,该插件将位于插件列表的“已安装”(Installed)分段,而非“项目”(Project)或“内置”(Built-in)分段。

Modules

Optional

对于包含源代码(和二进制文件)的插件,此模块列表应在启动时加载。请参阅下文了解更多信息。

模块描述符

对于包含代码的插件,此描述符文件将包含至少一个模块描述符。

{
    "Name" : "UObjectPlugin",
    "Type" : "Developer"
    "LoadingPhase" : "Default"
}

域名

信息

描述

Name

Required

将与该插件一起加载的插件模块的唯一名称。运行时,引擎的二进制文件夹下将存在相应的插件二进制文件,且模块使用此处指定的名称。对于包含源目录的模块,则模块的子文件夹树下将存在匹配的*.Build.cs文件。

Type

Required

设置模块的类型。有效选项有 RuntimeRuntimeNoCommandlet, DeveloperEditorEditorNoCommandletProgram。此类型决定了此插件模块适合加载的应用程序类型。例如,有些插件可能包括被设计为仅在编辑器运行时加载的模块。运行时模块将在任意情况下加载,即使在已经推出的游戏中也可以。开发者模块仅在开发运行时或编辑器版本中加载,绝不会在正在推出的版本中加载。编辑器模块仅在编辑器启动时加载。插件可使用不同类型的模块组合。

LoadingPhase

Optional

如指定,则控制在启动时加载插件的时间。这是高级选项,通常对此不作要求。有效选项有 Default(在未指定 LoadingPhase 时使用)、PreDefaultPostConfigInitPostConfigInit 允许在引擎完成关键子系统的启动之前加载该模块。PreDefault在法线阶段之前加载。通常,仅在您认为游戏模块对插件中的内容或插件代码中表明的类型有直接依赖性时才需要用到此选项。

WhitelistPlatforms

Optional

若指定,则提供将为其编译此模块的平台列表。若未指定,则将为所有平台编译此模块。

BlacklistPlatforms

Optional

若指定,则提供将不为其编译此模块的平台列表。若未指定,则将为所有平台编译此模块。

图标文件

和描述符文件一样,插件通常都有一个用于在编辑 UI 显示插件的图标文件。

文件名

信息

格式

描述

/Resources/Icon128.png

Required

128x128 PNG 文件

此图标在编辑器UI中代表着此插件。它将显示在插件用户界面,可从主窗口菜单访问。

插件示例

我们创建了几个不具备任何功能的插件示例,但您可以在开始创建自己的插件时将其作为空壳使用。这些示例均包含引擎源代码。

示例名称

信息

BlankPlugin

此插件为空壳,仅作为示范,展示构建新代码插件模块所需的多个最小空文件。

UObjectPlugin

用于展示如何声明自带Uobject类的简单空插件。

如需将这些示例用作构建插件的起始点:

  1. 将示例插件复制到新文件夹,将目录、文件和代码内容重命名,使之与您的新插件名称相匹配。请勿继续沿用现有名称,因为这会和与引擎一起打包的内置插件冲突。

  2. 在游戏项目目录下 创建“Plugins”文件夹,然后将插件复制到“Plugins”下的任意子目录。

    ExamplePlugins.png

  3. 重新构建C++项目文件。插件模块和源代码将显示在项目文件中项目目录下的目录中。

  4. 按常规方式 编译游戏项目。虚幻构建工具将检测这些插件,并按照对游戏的依赖情况进行编译!

  5. 启动编辑器(或游戏。)起初插件将是禁用状态,但您可以在编辑器UI中启用。

  6. 打开插件编辑器 (窗口(Window) -> 插件(Plugin)),搜索您的插件,并单击复选框启用即可。

  7. 重启编辑器。您的插件将在启动时自动加载。

打开 窗口(Window) -> 开发者工具(Developer Tool) 菜单下的 模块(Module) 查看器即可查看已加载的插件。 还可以使用代码调试器在插件的启动代码中放置一个断点,如*FBlankPlugin::StartupModule()*。

欢迎来到全新虚幻引擎4文档站!

我们正在努力开发新功能,包括反馈系统,以便您能对我们的工作作出评价。但它目前还未正式上线。如果您对此页面有任何意见与在使用中遭遇任何问题,请前往文档反馈论坛告知我们。

新系统上线运行后,我们会及时通知您的。

发表反馈意见