插件

创建虚幻引擎插件的方法。

Windows
MacOS
Linux
See Also

此页面将对在虚幻引擎4(UE4)工具中和运行时使用的 插件 开发与管理进行讲解。

在UE4中,插件是开发者可在编辑器中逐项目启用或禁用的代码和数据集合。插件可添加运行时gameplay功能,修改内置引擎功能(或添加新功能),新建文件类型,及使用新菜单、工具栏命令和子模式扩展编辑器的功能。使用插件可扩展许多现有UE4子系统。

现在如要创建插件,请参见新建插件 章节。

编辑器中的插件UI

可在 编辑 菜单打开插件编辑界面,查看当前安装的插件。

PluginsEditor.png

可在主"窗口"菜单访问插件编辑器。此界面显示当前安装的所有插件,可单独启用或禁用插件。

可使用左侧树形界面浏览类别。选择类别将显示该类别中的所有插件,及所有子类别中的插件。浏览各类别时,UI顶部将显示浏览路径记录,可快速跳转到更高级的类别。类别旁显示的数字表明该类别中可用插件数量。

PluginCategories.png

插件显示在主列表中,附有各插件的命名、图标、当前版本、文本描述、作者(和可选Web超链接),及插件当前是否启用。

利用顶部的搜索功能按钮可在列表中以命名搜索插件。

SearchingPlugins.png

在插件描述下方切换 已启用(Enabled) 复选框,可对活跃项目启用或禁用插件。可能需重启编辑器才能使变更生效。

插件剖析

含有代码的插件包含Source文件夹。此文件夹将包含一个或多个目录,其中包含插件的模块源代码。注意:插件常包含代码,但并非必要条件。参见插件中的代码 章节,了解更多信息。

含代码的插件拥有包含该插件编译后代码的 Binaries 文件夹,而临时版本产品文件将另存在插件目录中的 Intermediate 文件夹中。

插件可拥有自己的Content文件夹,其中包含特定于该插件的资源文件。参见插件中的内容 章节,了解更多信息。插件配置文件应使用和其他配置文件相同的规则放置:

  • 引擎插件:[PluginName]/Config/Base[PluginName].ini

  • 游戏插件:[PluginName]/Config/Default[PluginName].ini

插件不支持自身衍生数据缓存分布。

插件文件夹

为便于查找插件,须将其放置在项目中或引擎本身中的插件搜索路径。

插件类型

搜索路径

引擎

/[UE4根目录]/Engine/Plugins/[插件命名]/

游戏

/[项目根目录]/Engine/Plugins/[插件命名]/

也可将插件整理到基础Plugins文件夹下的子目录中。引擎将扫描基础Plugins文件夹下的所有子文件夹,查找要加载的插件,但不会扫描已找到插件下的子目录。

虚幻引擎通过在磁盘上搜索 .uplugin 文件来查找插件。将此类文件称为 插件描述文件。其是提供插件相关基本信息的文本文件。运行此类程勋时,引擎、编辑器和 UnrealBuildTool(UBT)将自动发现并自动加载插件描述文件。参见插件描述文件 章节,了解创建和自定义此类文件的方法。

插件中的代码

生成Visual Studio或Xcode的项目文件时,含有 Source 文件夹(包含 .Build.cs 文件)的插件将被添加到项目文件,以便导航到其源代码。编译游戏项目时,UBT将自动编译此类插件。

插件可含有任意数量的模块源目录。多数插件仅有一个模块(但可创建多个模块,例如插件包含纯编辑器功能时),及游戏期间要运行的其他代码。

插件源文件的大部分布局与引擎中其他C++模块相同。

在模块的 Source 目录(或其子目录)内,插件可在标头文件中声明新反映的类型(UCLASSUSTRUCT 等)。引擎的构建系统将检测此类文件,并按需要生成代码支持新类型。需遵守C++模块中使用 Uobjects 时的一般规则,例如在模块的源文件中包含生成的标头文件和模块 generated.inl 文件。

UE4支持共生模块和插件。通过在自身.uproject文件中启用插件,项目模块可依赖插件。类似地,通过在自身.uplugin文件中启用其他插件,插件可表明依赖性。但其中有一项重要限制:插件和模块将拆分为若干层级,仅能依赖同一级或更高级的其他插件或模块。例如,项目模块可依赖引擎模块,但引擎模块无法依赖项目模块。这是因为引擎(及其所有插件和模块)的级别高于项目,须能在无项目的情况下编译。以下图表展示了项目和模块间的依赖性层级:

PluginAndModuleDependency.png

箭头表明可能的依赖性。各插件或模块类型可依赖同级别或更高级别的其他插件或模块类型。

引擎插件

虚幻引擎4的 Engine 目录下包含部分内置插件。引擎插件和项目插件类似,但可用于所有项目。此类插件通常由引擎和工具程序员创建,目的在于提供可在多个项目中使用并能在单一位置维护的基线功能。利用此功能,用户可直接添加或覆盖引擎功能,而无需修改引擎代码。

插件中的内容

虚幻引擎支持包含游戏内容以及二进制代码的插件。为使用插件中的内容,须将插件描述文件中的"CanContainContent"设置设为"true"。

项目中的插件

插件位于项目目录的 Plugins 子文件夹下,将在引擎或编辑器启动时被探测和加载。

如插件包含具有 Source 文件夹(和 .Build.cs 文件)的模块,插件代码将被自动添加到生成的C++项目文件,以便在开发项目时开发插件。编译项目时,有可用源的插件都被作为游戏依赖项进行编译。

项目生成器将忽略无 Source 文件夹的插件,其不会出现在C++项目文件中,但若存在二进制文件,启动时仍将加载此类插件。

目前,无法将插件配置文件与项目打包。未来版本中可能会支持此功能,但目前需手动将此类文件复制到项目的 Config 文件夹。

在Epic商城分布插件

要打包插件,请点击 *打包……(Package...)* 链接,将插件打包到文件夹中进行分布。

PackagePlugin.png

插件描述文件

插件描述文件是命名以 .uplugin 结尾的文件。文件名的第一部分固定为插件命名。插件描述文件固定位于插件目录中,启动时将被引擎发现。

插件描述文件使用Json(JavaScript对象表示法 )文件格式。

描述文件示例

此范例描述文件来自引擎的 UObjectPlugin

{
    "FileVersion" :3,
    "Version" :1,
    "VersionName" :"1.0",
    "FriendlyName" :"UObject Example Plugin",
    "Description" :"An example of a plugin which declares its own UObject type.This can be used as a starting point when creating your own plugin.",
    "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"
        }
    ]
}

描述文件格式

描述文件为JSON格式的变量列表,此类列表为 FPluginDescriptor 类型。其中具有一个附加字段"FileVersion",其是文件结构中唯一的必需字段。"FileVersion"提供插件描述文件的版本,通常应设为引擎支持的最高版本(当前为"3")。由于此版本应用于插件描述文件的格式,而非插件本身,因此其可能不会频繁变化,也不应随插件后续版本的发行而改变。要与引擎旧版本进行最大化兼容,可使用较旧版本号,但不建议进行此操作。

欲了解其他支持字段的相关详情,参见FPluginDescriptor API参考页面。

布尔变量的字段命名删除变量命名中的首字母"b"。例如变量 bEnabledByDefault 对应"EnabledByDefault"字段。

模块描述符

对于包含代码的插件,描述文件中的"Modules"字段将包含至少一个条目。以下为范例条目:

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

各条目须具有"Name"和"Type"字段。"Name"是插件模块的唯一命名,将随插件而加载。在运行时,插件的"Binaries"文件夹中需存在正确的插件二进制文件,并带有指定模块命名。对于具有Source目录的模块,模块的子文件夹树中须存在匹配的".Build.cs"文件。"Type"设置模块的类型。有效的选项为:RuntimeRuntimeNoCommandletDeveloperEditorEditorNoCommandletProgram。此类型决定能加载模块的应用程序类型。例如部分插件可能包含仅在编辑器运行时加载的模块。将在所有情况下加载运行时模块,即使在已发行的游戏中,也需加载。仅在开发运行时或编辑器版本中加载开发者模块,不会发行版本中加载。仅在编辑器启动时加载编辑器模块。插件可使用不同类型模块的组合。

欲了解其他支持字段的相关详情,参见FModuleDescriptor API参考页面。

图标

与描述文件相同,插件需要在编辑器插件浏览器中显示的图标。该图像应为128x128的.png文件,名为"Icon128.png",保存在插件的"/Resources/"目录中。

新建插件

要新建插件,请使用编辑器插件浏览器中的 新建插件 按钮。

CreatePlugin.png

之后可选择要创建的插件类型,输入命名,并设置基本参数。

PluginTypes.png

新插件将显示在插件浏览器中,将在当前项目中启用。

Tags
Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback