安装插件¶

本章节介绍如何将 Modular Building System 安装到 Unreal Engine 项目中。

插件核心由 C++ 实现，但标准使用流程支持纯蓝图项目。正常情况下，蓝图项目无需创建 C++ 类或修改项目的 Build.cs 文件。

环境要求¶

项目	要求
Unreal Engine	Unreal Engine 5.4-5.8
项目类型	Blueprint 或 C++
插件类型	Runtime Plugin
操作系统	Windows
网络模式	单机、Listen Server
Dedicated Server	请参考当前版本说明

引擎版本

请使用与插件发布包匹配的 Unreal Engine 版本。不同引擎版本之间的 C++ 插件通常不能直接混用。

插件依赖¶

插件内部使用了部分 Unreal Engine 内置模块，例如：

Gameplay Tags
Niagara
Networking
Hierarchical Instanced Static Mesh

5.4 需要StructUtils 这些依赖会由插件模块自动加载，正常安装时不需要手动修改项目的 Build.cs。

通过 Fab 安装¶

通过 Fab 获取插件后，需要先将插件安装到对应的 Unreal Engine 版本。

基本流程如下：

在 Fab Library 中找到 Modular Building System。
选择目标 Unreal Engine 版本。
将插件安装到该引擎版本。
启动或重新启动 Unreal Editor。
打开需要使用插件的项目。
在插件管理窗口中启用插件。

如果插件已经安装到当前引擎版本，可以直接进入启用插件。

手动安装到项目¶

如果你获得的是独立插件文件夹，可以将插件放入项目的 Plugins 目录。

项目结构应类似：

YourProject/
├── Config/
├── Content/
├── Source/
├── Plugins/
│   └── ModularBuildingSystem/
│       ├── Config/
│       ├── Content/
│       ├── Resources/
│       ├── Source/
│       └── ModularBuildingSystem.uplugin
└── YourProject.uproject

如果项目中没有 Plugins 文件夹，可以手动创建：

YourProject/Plugins/

然后将整个插件目录复制到：

YourProject/Plugins/ModularBuildingSystem/

不要复制多余的外层目录

ModularBuildingSystem.uplugin 应直接位于插件根目录中。

正确：

Plugins/
└── ModularBuildingSystem/
    └── ModularBuildingSystem.uplugin

错误：

Plugins/
└── ModularBuildingSystem/
    └── ModularBuildingSystem/
        └── ModularBuildingSystem.uplugin

安装到引擎目录¶

也可以将插件放入 Unreal Engine 的插件目录：

UnrealEngine/
└── Engine/
    └── Plugins/
        └── Marketplace/
            └── ModularBuildingSystem/

项目级安装和引擎级安装的区别：

安装方式	说明
项目级安装	插件只对当前项目可用
引擎级安装	使用该引擎版本的多个项目都可以使用插件

开发和测试阶段更推荐使用项目级安装，因为更容易管理插件版本，也不会影响其他项目。

启用插件¶

打开 Unreal Editor 后：

打开 Edit。
选择 Plugins。
搜索：

Modular Building System

勾选插件旁边的 Enabled。
根据编辑器提示重新启动项目。

重启后，插件模块会在项目启动时加载。

验证插件是否成功启用¶

插件启用后，可以通过以下方式确认安装状态。

检查插件窗口¶

重新打开：

Edit → Plugins

搜索 Modular Building System，确认插件处于启用状态。

检查项目设置¶

打开：

Edit → Project Settings

在设置搜索框中搜索：

Building

如果可以找到 Modular Building System 相关设置，说明插件设置模块已经正确加载。

检查内容浏览器¶

如果插件包含示例内容，需要在内容浏览器中启用：

Settings → Show Plugin Content

启用后，可以在内容浏览器中看到插件内容目录。

插件核心 C++ 功能不依赖是否显示 Plugin Content。该选项只影响插件资源是否显示在内容浏览器中。

纯蓝图项目¶

插件可以安装到没有项目 C++ 模块的纯蓝图项目中。

标准蓝图使用流程包括：

添加 BuildingBuildComponent
创建建筑数据资产
配置建筑 Mesh 或 Actor Class
开启建造模式
确认、移动和删除建筑
监听建造结果事件
使用多人建造功能
实现插件提供的蓝图接口

正常使用不要求：

创建空白 C++ 类
修改项目 Build.cs
修改插件源码
手动编译插件

出现重新编译提示

如果蓝图项目启动时提示插件模块缺失或需要重新编译，请确认：

- 插件版本与 Unreal Engine 版本一致
- 插件包包含对应平台的编译文件
- 插件文件没有损坏
- 插件没有被放入错误的嵌套目录

C++ 项目¶

在普通使用场景中，即使项目包含 C++，也不需要手动添加插件模块依赖。

只有当项目 C++ 代码需要直接包含插件头文件并调用插件 API 时，才需要在项目模块的 Build.cs 中添加依赖。

例如：

PrivateDependencyModuleNames.AddRange(
    new string[]
    {
        "ModularBuildingSystem"
    }
);

如果插件类型需要被项目的公共头文件暴露，可以根据实际情况加入：

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

一般情况下，优先使用 PrivateDependencyModuleNames。

修改 Build.cs 后，需要重新生成项目文件并编译项目。

首次启动¶

第一次启用插件后，建议检查以下内容：

插件是否成功启用。
Project Settings 中是否显示插件设置。
插件所需的碰撞通道是否已经配置。
插件使用的 Gameplay Tags 是否正确加载。
示例内容是否可以显示。
BuildingBuildComponent 是否可以添加到蓝图 Actor。
是否可以创建插件提供的建筑数据资产。

打包前检查¶

在正式打包项目前，建议确认：

插件已在目标项目中启用
插件版本与目标引擎版本一致
建筑数据资产可以被正确加载
插件内容没有被错误排除
所需 Gameplay Tags 已包含在项目配置中
碰撞通道与碰撞配置已经创建
Blueprint-only 项目可以完成 Development 打包
多人项目已经完成客户端和服务器测试

不要只在编辑器 PIE 中验证插件。正式发布前，应至少测试一次独立运行或打包后的 Development 版本。

常见问题¶

插件没有出现在 Plugins 窗口中¶

检查：

ModularBuildingSystem.uplugin 是否存在
插件目录是否放在项目的 Plugins 文件夹中
是否多嵌套了一层同名目录
插件描述文件是否损坏
当前 Unreal Engine 版本是否受支持

提示插件是为其他引擎版本构建的¶

说明插件包与当前引擎版本不一致。

请安装与当前 Unreal Engine 版本匹配的插件包，不建议直接忽略该提示。

插件启用后项目无法启动¶

可以暂时关闭编辑器，然后打开项目的：

YourProject.uproject

检查 Plugins 配置，或暂时将插件目录移出项目，确认问题是否来自插件加载。

同时查看：

YourProject/Saved/Logs/

中的项目日志。

内容浏览器中看不到插件资源¶

启用：

Content Browser → Settings → Show Plugin Content

找不到 Building Data Asset¶

确认：

插件已经启用并重启
创建的是 Data Asset
插件模块已经成功加载
没有使用不兼容的插件版本

下一步¶

安装完成后，建议按照以下顺序继续：快速开始