编辑器工具
插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 面向读者:用插件编辑器工具制作 Sequence 叙事内容的内容方(编辑器侧工作流) 跳转:📘 运行机制(叙事数据结构 / 推进驱动 / 虚空·引导·报幕语义)→ 06 核心组件 | 📘 安装 / DA 基础 → 02 快速入门 | 📘 路径设计原则 → 05 大空间最佳实践
⚠️ 本篇全部内容为 Editor 模块能力,仅 Win64 编辑器可用;打包运行时不包含。源码包 / binary 包均随插件分发。
目录
-
- 工具总览与入口
-
- InspectorPanel(配置自检)
-
- 内容制作工作流(五步)
-
- 场景搭建:ActBuilder / Act / Plot 与 EdMode 加点
-
- SettingPanel
-
- BestPath 路径编辑器(独立窗口)
-
- 导出产物与消费契约(PathExport)
-
- 已知限制与注意事项
1. 工具总览与入口
两个入口共用同一组菜单项(编辑器菜单栏 "YOMOV SDK" 或主工具栏 "YOMOV SDK" 下拉按钮(齿轮图标)):
菜单项 | 功能 |
|---|---|
Create ActBuilder | 在当前关卡一键创建叙事搭建起点(ActBuilder + 首个 Act + 首个 Plot,见 §4) |
SettingPanel | 打开设置面板(模式切换 / Single 配置 / Sequence 烘焙与导出 / 边界效果配置,见 §5) |
InspectorPanel | 打开配置自检面板:检查三项配置资产(两个运行时 DA + |
Open BestPath Editor | 打开 BestPath 路径编辑器独立窗口(Act 场馆摆放,见 §6;无 Narrative 上下文时会警告并中止) |
2. InspectorPanel(配置自检)
装完插件的第一件事:用 InspectorPanel 检查并创建必需的配置资产(对齐 Unity 版 InspectorPanel 的「失败才显示 + Autofix 修复」口径)。
入口:菜单 YOMOV SDK → InspectorPanel(MajorTab;重复打开自动聚焦已有窗口)。
面板结构:标题 + [Refresh] 按钮 + 逐项检查行——
检查项 | 规范路径 | 期望类 |
|---|---|---|
|
|
|
|
|
|
|
|
|
-
通过 → 绿色 ✓ 行
-
失败(资产缺失 / 类不匹配)→ 红色 ✗ + 提示文案 + [Autofix] 按钮
[Autofix] 做什么:按 C++ ctor 默认值在规范路径创建该资产 → 注册进 AssetRegistry 并落盘 → ReloadConfig → 立即重跑检查刷新面板。
✅ 幂等:资产已存在时直接返回,不覆盖你已配好的内容。
检查时机:打开 Tab 时检查一次 + 手动 [Refresh](不做定时轮询——资产存在性变化频率低,手动刷新足够)。
为什么必须用这个入口:两个 DA 的路径必须与
UConfigManagerSubsystem的加载路径一致(上表即规范路径)——手动在别处创建不会被加载。用 [Autofix] 一步到位,且顺带保证资产类正确。 第三项 TestNarrative 的性质不同(1.2.1 起纳入):它不是 ConfigManager 加载项,而是 FlowController Sequence 模式的叙事 fallback 默认资产(插件不分发)——未自配叙事 BP 时,叙事链从它兜底。Autofix 补建的是空 StoryActs 资产(仅内容起点,数据需按 §3 工作流另行配置);内容方自建的叙事 DA 仍由 SettingPanel 显式选用,不在检查列。DA_BoundaryEffectConfig随插件包分发,无需创建。
3. 内容制作工作流(五步)
① 新建 Narrative DA → ② 场景搭建(ActBuilder/Act/Plot + EdMode 画多边形)
→ ③ SettingPanel [Update Act Sequence] 烘焙 → ④ [Export] 出数据 / 或 BestPath 摆放后 [保存路径]
→ ⑤ Ctrl+S 手动保存(面板只标脏,不落盘!)
步 | 操作 | 产物 |
|---|---|---|
① | Content Browser 右键 → Miscellaneous → Data Asset → | DA 骨架( |
② | 菜单 Create ActBuilder → Details 面板按钮链建 Act / Plot → EdMode / 拖拽画多边形 | 场景摆放 Actor + 多边形数据 |
③ | SettingPanel 选 Narrative + 填 |
|
④ | [Export](出 PathExport 三件套 + 截图)或 [Open BestPath Editor] 摆放 → [保存路径](双写) | PathExport 产物 + |
⑤ | Ctrl+S 保存资产与关卡 | 落盘(⚠️ 工具只 MarkPackageDirty) |
4. 场景搭建:ActBuilder / Act / Plot 与 EdMode 加点
4.1 创建链(Details 面板按钮)
菜单 Create ActBuilder(单例守卫:已存在会警告并选中既有实例)在当前关卡生成 AYomovActBuilderActor + 首个 AYomovActDescriptor(Act_01)+ 首个 AYomovPlotBoundary(单事务,可 Undo)。之后的层级靠 Details 面板按钮续建:
选中对象 | 按钮 | 功能 |
|---|---|---|
ActBuilder | [Create Act] | 追加一个 ActDescriptor |
Act(ActDescriptor) | [Create Plot] | 追加一个 PlotBoundary(attach 为该 Act 子 Actor) |
[Generate Act Boundary] | 由子 Plot 多边形并集重生成 | |
[Generate Main Area] | 重生成主区域( | |
[Draw Arrival] / [Draw Exit] | 进入 EdMode 手画进入区 / 出口点(出口为单点覆盖写) | |
Plot(PlotBoundary) | [Draw PlotBoundary] / [Draw BestView] | 三态按钮,见下 |
Plot 三态按钮语义:
状态 | 按钮显示 | 行为 |
|---|---|---|
未画 | [Draw xxx] | 进入 EdMode,视口左键点地面加点 |
已画 | [Edit xxx] | 退出 EdMode,改用 Visualizer 拖拽编辑(拖顶点 / 拖边中点插点 / 选中点 Delete 删点) |
绘制中 | [Quit] | 退出 EdMode |
4.2 ActBoundary EdMode 与可视化
-
进入:上述按钮,或视口 Modes 面板选 ActBoundary 编辑模式。ESC 退出
-
加点:左键点击地面;
ActExit为单点覆盖写;主区域(ActMain)只能 Generate、不可手画 -
未选中常显轮廓(不用选中也能看到画了什么):Act = 绿色多边形;Plot = 橙色多边形;另有 Billboard 图标标识
-
Visualizer 配色:PlotBoundary 深橙(编辑中金色)、BestView 钢蓝、GuidePoint 绿、BestView 越出 PlotBoundary 红圈警告;Act 侧进入区青色顶点、出口点红点
5. SettingPanel
5.1 面板布局
菜单 SettingPanel 打开(MajorTab,重复打开自动聚焦已有窗口):
┌ LBEPath Type 下拉(Single / Sequence,写回 DA_DataAsset)─────────┐
│ ▼ Single Config 区(8 字段行内编辑) │
│ AnchorPoint / AnchorRotationY / ActSizeLength / ActSizeWidth │
│ FixedSize / ShowBoundary / BoundaryInteraction / NearDisplay… │
│ ▼ Sequence 区(仅 Sequence 模式显示) │
│ Narrative 资产下拉 [+刷新] · SourceScenes 编辑 · Act Units 只读 │
│ [Update Act Sequence] [Export] [Open BestPath Editor] │
│ ▼ Act Runtime Effect 区(Single/Sequence 恒可见) │
│ DA_BoundaryEffectConfig 属性面板(虚空/引导/报幕配置) │
│ [Save & Apply] │
└──────────────────────────────────────────────────────────────────┘
[Save & Apply](1.2.3 起,原 [Apply])= 先保存到磁盘,再热重载(ConfigManagerSubsystem.ReloadConfig + 虚空 / 边界效果管理器 ReloadConfig),改 DA 字段后无需重启编辑器 / PIE:
-
保存只写脏包(ConfigData / BoundaryEffectConfig);保存失败会中止 Apply,防止用磁盘旧值回滚未保存的修改
-
LBEPathType 模式切换会自动落盘(无需再点按钮)
-
旧的「只 Reload 不落盘」行为已取消——未保存的修改不会再被静默丢弃
5.2 [Update Act Sequence](烘焙)
把场景摆放烘焙进 Narrative DA。依次加载 SourceScenes 场景,扫描 ActDescriptor(attach 顺序 = Act 顺序)与其子 PlotBoundary(attach 顺序 = Plot 顺序),覆盖重写StoryActs。
烘焙内容:
项 | 行为 |
|---|---|
| = 子 Plot 多边形并集(派生,不手画) |
| = |
| 每次烘焙重定位到 ActArea 几何中心(XY;旋转 / Z 不动)——⚠️ 手改 Anchor 会被下次 Update 冲掉 |
| 跨场景重名自动加 |
|
|
守卫与安全:PIE 运行中拒绝、Untitled 地图拒绝、dirty 关卡先弹保存框(取消 = 中止);全程事务化 + StoryActs 备份,校验失败回滚不写半截;完成后自动还原原场景。
内置校验(失败项会在结果文本中列出):ActArea 少于 3 点 / 主区域·进入区越出 ActArea / 出口点出界 / Duration ≤ 0 / PlotBoundary 自交 / Plot 重叠 ≥ 90% / ActName 重复 / PlotID 重复。
Update 成功后若 BestPath 已有旧摆放数据,BestPath 窗口会显示失效提醒横幅(提示重新摆放 / 保存)。
5.3 [Export]
导出内容数据三件套 + 俯视截图到 <项目目录>/PathExport/(详见 §7):
-
先按 §5.2 同源跑一遍 Update(保证导出的是最新烘焙值)
-
导出
ActSetting.json+Stage.json+TestMapEditData.map -
逐 Act 出俯视截图
{ActName}.png(守卫:PIE 中跳过、Untitled 跳过、首次切场景前统一弹保存框——取消只中止截图,JSON 产物不受影响;完成后还原原地图)
6. BestPath 路径编辑器(独立窗口)
对齐 Unity 路径设计器的纯 2D 画布独立窗口(MajorTab,不切换场景)。三个入口:菜单 / SettingPanel Sequence 区按钮(带当前 Narrative 上下文)/ 蓝图函数库 UBestPathEditorFunctionLibrary(OpenBestPathEditor / CloseBestPathEditor / SaveBestPathPath / RunBestPathValidation / SetBestPathActVisible,Python 可调)。
为什么「最佳路径」重要(二元作用):① SDK 接入阶段——按本地测试场地尺寸(如 6×8、8×10m)摆一条路径,完成本地全真模拟测试;② 内容发行阶段——导出的是导演视角的最佳体验路径(角度衔接、旋转关系),分发算法自动适配场馆地图时会读取该路径中单元的相对位置与旋转角度作为计算权重,尽可能还原最佳体验。画布摆放不是随手排,是在给算法定「体验基准」。路径设计原则(尺寸 / 衔接 / 三区)见 05 大空间最佳实践。
6.1 画布元素
元素 | 样式 |
|---|---|
场馆多边形(ArcadePoly) | 白色线框 |
障碍物(Obstacles) | 灰色描边 |
Act 边界 | 绿 2px;选中蓝 4px;校验失败红 4px |
进入区 / 核心区 | 蓝 / 紫 填充 |
出口点 | 黄色圆点(0.8m 半径) |
Locate / Start / End 标记 | 青箭头 / 黄箭头 / 红点(画布级固定标记) |
Act 编号 | 白色数字 |
场馆四边尺寸标注(1.2.3):上 / 下边显示横向跨度、左 / 右边显示纵向跨度(场馆地图帧 AABB,米),便于按场馆实际尺寸摆放路径。
6.2 交互
操作 | 方式 |
|---|---|
选中 + 拖动 Act | 左键点选后拖动(拖动范围限制在场馆外扩 50% 内) |
旋转 | Shift + 左键拖动(水平方向 = yaw ±0.5°/px) |
平移画布 | 中键 / 右键拖动 |
缩放 | 滚轮(0.1~10 倍,锚定鼠标) |
微调 | 方向键 nudge ±1px;Shift+上/下 = Yaw ∓1° |
撤销 / 重做 | Ctrl+Z / Ctrl+Y(拖动与数值提交各自成事务) |
数值输入框语义:X / Y 单位米(场馆地图帧:map.x = UE.Y、map.y = UE.X);Angle 单位度、逆时针为正(内部为 −Yaw,与 Unity 视觉一致)。
6.3 Act 列表与显隐
左栏 Act 列表:每行 眼睛开关 + NN ActName;LRU 显隐上限默认 3(可调 1~10)——点亮新的超过上限自动熄灭最旧的。
左栏另有 「Act 截图」开关(1.2.3):勾选后在画布对应 Act 区域贴 PathExport/{ActName}.png 俯视截图作底图(与 [Export] 截图同源同取景)。截图缺失时该处不显示底图、不缓存失败结果——补出截图后重新勾选即可。
6.4 摆放语义(重要)
有 BestPath.json 摆放数据时(正常路径):画布拖动 / 旋转只写场馆摆放数据,绝不改动关卡 Anchor 与点表——Anchor 只来自关卡 Update 烘焙(§5.2),画布不碰它,保证运行时边界定位(BRA = Anchor − Rot × Position)不被写坏。
6.5 校验与保存
校验三条规则(不合法的 Act 画布红显):
-
每个 Act 的
ActArea完全落在场馆多边形内 -
不与任何障碍物相交
-
上一 Act 的出口点落在当前 Act 的进入区内
[保存路径](一键双写):
-
写
ActSetting.json→<项目>/PathExport/ -
写
BestPath.json→ <项目>/Content/PathData/(运行时唯一读取源;任一失败 = 整体失败) -
重新出每 Act 俯视截图
-
清除失效横幅;浮泡提示「Ctrl+S 保存资产以持久化」——⚠️ 仍需手动 Ctrl+S
7. 导出产物与消费契约(PathExport)
导出目录 <项目目录>/PathExport/,供游幕内容平台消费(按「Position + 相对点」贴图画区域;截图作 2D 画布底图):
产物 | 内容 | 关键约定 |
|---|---|---|
ActSetting.json |
| 坐标 = Unity 世界(米,Y-up): |
Stage.json |
| 运营侧分段清单 |
TestMapEditData.map | 场馆数据( | map 帧 2D 米( |
{ActName}.png | 每 Act 正交俯视截图 | 最长边 512px 按多边形宽高比;多边形界外像素透明(alpha 蒙版);画面方向 图 x → 世界 +Y、图 y(向下)→ 世界 −X;文件名与 |
BestPath.json |
| ⚠️ 保存位置在 Content/PathData/(运行时唯一源), |
俯视截图的遮罩 / 方向语义与 Unity 原版消费链对齐(图 x = +Y、图 y↓ = −X);消费方按图片实际尺寸贴图即可。
8. 已知限制与注意事项
-
Details 面板数值直改 PlotBoundary 不会自动重生成父 Act 的 ActAreaPoints(只有视口拖拽结束与 EdMode 加点两条路径会触发)——数值路径改完需手动点 [Generate Act Boundary]
-
GuidePoint 每次 PlotBoundary 变更都会被自动重置为顶点平均(对齐 Unity 行为);手动拖过的
GuidePoint会在下次改动时被覆盖 -
Update 是全量覆盖重烘:
StoryActs清空重写;Anchor 每次重新居中(手改 Anchor 会被冲掉——Anchor 不是手配字段) -
BestPath 编辑器只 MarkPackageDirty、不自动落盘——保存路径后仍需 Ctrl+S 保存关卡 / DA(SettingPanel 的配置写回在 1.2.3 起会自动落盘,见 §5.1)
-
MainAreaPoints 是只读派生量([Generate Main Area] 生成,ActArea 内缩 100cm),EdMode 中不可手画
-
ActSetting.json的Position恒为零:Unity 侧 Act 摆放位置以 BestPath.json 的 locate 帧 Position 为准 -
旧版
BestPath.json不在唯一源位置时会回退读 map 同目录 /PathExport(平滑迁移,无需手动搬) -
Unity 的 Plot Type(Walking / Vehicle)UE 暂未提供 Sequence 侧等价物——载具移动效果走 Single 模式 Marker 方案(见 01 §6.3)