游戏引擎 / 系统课时

用插件拆分独立功能

用插件拆分独立功能

当一套交互、存档、编辑器工具或通用 Gameplay 能力已经不再属于某个关卡或单一项目模块时,可以把它提取为 Plugin。关键不是“多建一个目录”,而是明确 Plugin、Module、公开 API 与项目代码之间的依赖方向,让功能能够独立编译、启用和复用。

学习目标

  • 区分 Plugin 容器与 C++ Module 编译边界。
  • 建立最小可编译的 Runtime Plugin,并正确声明模块依赖。
  • 判断哪些代码应该进入插件,哪些仍应留在项目主模块。

先划清可复用边界

一个插件可以包含代码、资源和多个 Module;真正参与 C++ 编译和依赖分析的是 Module。适合抽离的能力通常有稳定职责,例如通用交互接口、存档框架、网络诊断或编辑器批处理工具,并且不应该反向依赖某个具体游戏的角色类、关卡类或项目主模块。

项目模块与插件模块的依赖边界

抽离前先问三个问题:它能否在不知道具体游戏规则的情况下成立;它的公开接口是否可以保持稳定;另一个项目拿走它后是否只需声明依赖而不用复制业务代码。三个答案越接近“是”,越适合做成插件。

建立最小Runtime插件

项目级插件通常放在项目根目录的 Plugins 下。以下示例使用 InteractionTools,其 .uplugin 描述符声明一个 Runtime Module。CanContainContent 设为 false,表示本例只承载代码;如果插件需要自带资产,应根据实际需要改为 true。

json
{
  "FileVersion": 3,
  "Version": 1,
  "VersionName": "1.0.0",
  "FriendlyName": "Interaction Tools",
  "Description": "Reusable interaction helpers.",
  "Category": "Gameplay",
  "CanContainContent": false,
  "Modules": [
    {
      "Name": "InteractionTools",
      "Type": "Runtime",
      "LoadingPhase": "Default"
    }
  ]
}

该描述符生效后,Unreal Engine 会把 InteractionTools 识别为插件模块,并按 Runtime 模块参与目标构建。模块目录还需要同名的 InteractionTools.Build.cs 来声明 Unreal Build Tool 依赖。

csharp
using UnrealBuildTool;

public class InteractionTools : ModuleRules
{
    public InteractionTools(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

        PublicDependencyModuleNames.AddRange(
            new[] { "Core" }
        );

        PrivateDependencyModuleNames.AddRange(
            new[] { "CoreUObject", "Engine" }
        );
    }
}

这里把仅在实现内部使用的 CoreUObject 和 Engine 放进私有依赖,避免无必要地把依赖传播给消费方。若插件的 Public 头文件直接暴露了某模块的类型,就需要把对应模块提升到 PublicDependencyModuleNames。

让模块拥有明确入口

最小模块需要实现 IModuleInterface 并用 IMPLEMENT_MODULE 注册。下面的入口在模块加载时打印一条日志,便于确认 .uplugin、模块名和 Build.cs 三处名称是否一致。

cpp
#include "CoreMinimal.h"
#include "Modules/ModuleManager.h"

class FInteractionToolsModule final : public IModuleInterface
{
public:
    virtual void StartupModule() override
    {
        UE_LOG(LogTemp, Display, TEXT("InteractionTools module started"));
    }
};

IMPLEMENT_MODULE(FInteractionToolsModule, InteractionTools)

预期输出:插件启用且项目成功编译后,启动编辑器或运行目标时可以在日志中看到模块加载信息;日志前缀的时间等动态部分可能不同。

text
LogTemp: Display: InteractionTools module started

消费该插件 API 的项目模块,还需要在自己的 Build.cs 依赖列表中加入 InteractionTools。只有真正被 Public 头文件需要的插件类型才应形成公开依赖,否则优先保持私有依赖,减少重新编译范围。

把运行时代码和编辑器代码分开

如果插件同时包含运行时能力和自定义编辑器面板,不要让 Runtime Module 直接依赖 UnrealEd。更稳妥的做法是增加一个 InteractionToolsEditor 模块,把它的 Type 设为 Editor,再让 Editor Module 依赖 Runtime Module。

这种拆分能避免编辑器专用依赖进入 Shipping 目标,也让运行时插件保持更小的依赖面。插件可以拥有多个模块,因此“一个功能一个插件”并不意味着所有代码都必须塞进同一个 Module。

验证抽离是否真的成功

完成迁移后,先关闭旧项目主模块中对应实现,重新生成项目文件或刷新 IDE 工程,再做一次完整构建。随后启用插件启动项目,确认模块日志出现,并让项目代码只通过插件公开接口访问能力。

最后做一次“反向依赖检查”:搜索插件源码中是否还包含项目专属头文件、项目模块名或具体关卡类型。如果插件必须引用这些内容才能编译,它仍然只是被移动了目录,还没有形成真正可复用的模块边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用插件拆分独立功能

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通