JinYu
/
ProtypeProject
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ProtypeProject/设计文档/玩法编辑器使用手册.md

311 lines
14 KiB
Markdown
Raw Normal View History

Extend gameplay editor to support all 10 table types with ActivityNodeBase architecture
2026-03-30 19:45:49 +08:00
# 玩法编辑器使用手册
## 1. 设计目的
优化版本并行开发效率，缩短特殊玩法需求频繁迭代功能的开发周期。
---
## 2. 工作流
对应负责人开启活动需求统筹表 → 下游各组资产制作完成后 → 根据需求统筹表描述放到对应路径提交上传 → **策划通过玩法编辑器进行配置好索引表并上传** → 在引擎内使用导入工具检查资源。
---
## 3. 配置说明
活动玩法会涉及到场景资源、镜头资源、UI资源、特效资源。所有资源会配表做静态字典映射，在开启活动模块时根据映射加载对应资源。**行为树逻辑编辑器在节点引用时会从对应字典内进行查找引用。**
---
## 3.1 行为树配置表（自定义 name）
### 工作表1：玩法关卡配置表
用来索引玩法场景的逻辑 ID、场景资源、地图坐标打点 list、默认主相机。
| Doc | 行为树ID | 关卡备注 | 场景名称 | 地图打点组 | 是否关闭加载画面 | 默认相机ID |
|------|------------------|---------|-------------|------------|--------------------------|----------|
| Name | ActivityStageID | Doc | SceneName | MapInfo | CloseLoadingDelaySeconds | CameraID |
| Type | Int | String | String | ID | Float | Int |
> 打开：**功能编辑器**
---
### 工作表2：行为树逻辑表
配置行为树头文件和行为树逻辑本身。
| 列名 | 说明 |
|-----------|-------------------------------------------------------------|
| 行为树ID | 全局唯一标识（如 301502490） |
| 说明（注释）| 行为树文件说明 |
| 节点 | 各级子节点名称（可展开多列） |
| 行索引ID | 行为节点在行为树中的引用 ID |
**节点层级结构说明（树形）：**
```
行为树ID: 301502490 （行为树文件 平行）
├── 组合 方法:关卡通用关卡赋值
├── 组合 方法:关卡初始化
└── 后面是你自己的逻辑
行为树ID: 30150249 （行为树逻辑正文 顺序）
├── 组合 方法:关卡预准备
├── 平行
│ └── 组合 方法:关卡通用集合
└── 后面是你自己的逻辑
```
**行为树关键说明：**
1. **【关卡ID+0】** 为头文件，里面的逻辑只执行一次，用来声明初始数据或执行一些初始化逻辑。
2. **【关卡ID】** 后开始是行为树正文，主要写正式逻辑，默认1秒运行60次（根据性能需求可调整到1秒20次）。
3. **【行索引】** 会在当前行有子功能节点时打表自动生成，方便报错时定位行数。
4. **【组合方法】** 封装函数或子树，类似行为树的子树结构一处理一些通用赋值，比如开场是否隐藏UI、是否播放某个入场动画、对多个字典进行赋值等等。
5. 行为树默认包含四个基础执行节点：
- **平行**：执行该节点下的所有子节点并返回true，无论子节点是否执行成功。
- **顺序**：该节点下一旦有子节点返回false则停止执行返回false，子节点全部返回true该节点才返回true。
- **选择**：该节点下一旦有子节点返回true则停止执行返回true，子节点全部返回false该节点才返回false。
- **乱选**：随机执行一个子节点，结果为true则返回true，结果false返回false。
6. 需要一个组合方法在头文件里分别在黑板里创建1#（当前行为树域）、2#（角色域）、3#（自定义域）、4#（系统全局域）、UI、相机、特效、演出配置的映射字典（**或者是外部Data管理，功能节点默认找对应字典**）。
---
### 工作表3：行为树节点查询与说明（注释用）
| 节点类型 | 描述 | 中文节点映射 | 参数1 | 参数2 | 参数3 | 参数4 | 参数5 |
|-------------------|----------------------------------------------------------|-------------|-------------|--------------|-------|-------|-------|
| DoGetTime | 参数1（帧数）= 当前关卡时间（帧数）+ 参数2（秒转帧数） | int赋值时间 | int 帧数存值 | fix 时间单位秒 | | | |
| CheckNpcCamp | 比较阵营是否相等或包含参数1NPC参数2阵营（包含、相交、相等都是队友） | 比较阵营 | int 自定义 | int 自定义 | | | |
| DoSetFightTarget | 设置Npc1（参数1）的攻击目标为Npc2（参数2） | 设置战斗目标 | int Npc1 | int Npc2的Id | | | |
---
### 工作表4：组合节点说明（同工作表3）
| 组合树ID | 组合树类型 | 注释 |
|-----------|-----------|------|
| String | 节点名称 | |
| 200009 | 万法:关卡初始化 | |
| 200010 | 万法:关卡预准备 | |
---
## 3.2 ActivityUiLut
UI 资源。填写需要使用的关卡和映射 ID，可以填 String。
| 关卡ID | UI映射ID | Prefab路径 |
|-------|---------|-----------|
| int | int | path |
---
## 3.3 ActivityCameraLut
相机资源，配置同上。
| 关卡ID | Cam映射ID | Prefab路径 |
|-------|----------|-----------|
| int | int | path |
---
## 3.4 ActivityFXLut
特效资源，配置同上。
| 关卡ID | FX映射ID | Prefab路径 |
|-------|---------|-----------|
| int | int | path |
---
## 3.5 ActivityMapInfoLut
地图打点存储表，需要对应的地图点位编辑器。
| infoID | 点位ID | 坐标 | 点位ID | 坐标 | 点位ID | 坐标 | 点位ID | 坐标 |
|--------|---------|---------|---------|---------|---------|---------|---------|---------|
| int | String | Vector3 | String | Vector3 | String | Vector3 | String | Vector3 |
---
## 3.6 ActivityDialogInfoByStage
活动文本 UI 配置索引表。文本配置 ID 就是下面 DialogInfo 配置表的 name。
| 玩法关卡ID | 对应文本配置表 |
|----------|-------------|
| int | String |
---
## 3.7 DialogInfo + 自定义序号
具体文本配置（**与行为树一样，每个策划一张自己的 dialoginfo，需要先跟本地化管线讨论**）。
| id | isMask | MaskTarget | ClickKey | DialogType | UIType | PrefabPath | Name | Text | Duration | Params1 | Params2 | Params3 | Params4 | Params5 |
|--------|--------|---------------|---------|------------|--------|----------------------|---------|-----------|---------|---------|---------|---------|---------|---------|
| 配置ID | 是否开启蒙层 | 蒙层位置（万分比屏幕坐标） | 关闭蒙层键值 | 战中类型 | UI样式（变同类型战中样式） | UI预制体路径（默认不填写） | 显示角色名 | 正文（支持富文本） | 显示时间 | 特殊参数1 | 特殊参数2 | 特殊参数3 | 特殊参数4 | 特殊参数5 |
| int | bool | 万分比屏幕坐标 | int | int | int | | String | 对话正文 | float | | | | | |
**行为树对应功能节点：**
| 节点名称 | 参数1 |
|--------------|-------------|
| DoShowDialog | DialogInfoID |
| int | int |
---
## 4. QA & Debug
1. 上传对应行为树前需要策划自检，流程是否可以整跑通，过程中是否有节点报错，根据对应报错 ID 进行 Debug。
2. 资源检查：需要策划导入时自行检查资源是否与需求对应，是否在导入时出现失索引。
3. 提测 QA 后，QA 如发现流程卡死或报错，需要先向策划负责人提单，策划检查判断确定是非配置问题，再向其他对应下游提出修改需求。
---
## 5. 玩法编辑器工具操作指南
### 5.1 文件结构
```
Assets/BP_Scripts/GameplayEditor/
├── Core/
│ ├── GameplayGraph.cs ← 自定义 Graph 类型（Asset 本体）
│ ├── GameplayNode.cs ← 节点数据模型（含9个业务字段）
│ └── GameplayConnection.cs ← 节点连线类型
├── Export/
│ ├── ExcelExporter.cs ← Canvas → CSV 导出逻辑
│ └── ExcelImporter.cs ← CSV → Canvas 导入逻辑
├── GameplayEditorWindow.cs ← 编辑器窗口 UI
├── GraphDataSchema.cs ← 字段映射配置（ScriptableObject）
├── GraphExcelSyncManager.cs ← 运行时同步组件
└── ExcelDataProvider.cs ← CSV 读写基础工具
```
---
### 5.2 快速开始
**第一步：创建 GameplayGraph Asset**
在 Project 窗口中右键 → **Create → NodeCanvas → Gameplay Graph**，命名为关卡名，例如 `Level01Graph`。
**第二步：创建 GraphDataSchema 配置**
右键 → **Create → GameplayEditor → GraphDataSchema**，命名为 `Level01Schema`，在 Inspector 中可查看字段映射关系（用于编辑器窗口右侧展示）。
**第三步：打开玩法编辑器窗口**
菜单栏 → **Window → Gameplay Editor**
```
┌──────────────────────────────────────────────────────────────┐
│ [Graph 拖槽] [Schema 拖槽] [导出 Canvas→CSV] [导入 CSV→Canvas] │ ← 工具栏
├─────────────────────┬────────────────────────────────────────┤
│ Canvas 可视化编辑 │ CSV 字段映射 │
│ 显示所有节点列表 │ 显示 Schema 中配置的字段映射关系 │
└─────────────────────┴────────────────────────────────────────┘
```
将 `Level01Graph` 和 `Level01Schema` 分别拖入工具栏对应拖槽。
**第四步：在 Canvas 中编辑节点**
双击 `Level01Graph.asset` 打开 NodeCanvas 编辑器，右键画布 → **Add Node → GameplayEditor → GameplayNode** 添加节点。
点击节点在 Inspector 中编辑以下字段：
| 字段名 | 类型 | 说明 |
|-------------------|--------|---------------------------------------------------|
| Level ID | int | 关卡编号 ID（对应 ActivityStageID） |
| Node ID | int | 节点唯一 ID（**同一 Graph 内不能重复**） |
| Node Layer | int | 节点层级（0 为顶层根节点） |
| Event Type Group | string | 事件类型组，多个用 `\|` 分隔，如 `1\|2\|3` |
| Priority | string | 优先级权重，多个用 `\|` 分隔，如 `10\|20` |
| Event Mapping ID | int | 事件 ID 映射值（对应各 Lut 表中的映射 ID） |
| Interact Visible | bool | 交互时是否显示该节点 |
| Node State | bool | 节点是否处于可进入状态 |
| Parent Node ID | int | 父节点的 Node ID，**-1 表示根节点（无父节点）** |
拖拽节点端口建立连线，连线关系在导入时会根据 `ParentNodeID` 字段自动重建。
**第五步：导出 Canvas → CSV**
工具栏点击 **"导出 Canvas → CSV"**，输出到 `Assets/玩法编辑器.csv`。
生成格式（行1=字段名，行2=类型，行3=说明，行4起=节点数据）：
```
LevelID,NodeID,NodeLayer,EventTypeGroup,Priority,EventMappingID,InteractVisible,NodeState,ParentNodeID
int,int,int,string,string,int,bool,bool,int
关卡编号ID,节点ID（唯一）,节点层级,节点事件类型组（|分隔）,优先级权重（|分隔）,存储事件ID映射,交互是否可见,节点是否可进入,父节点ID（-1表示无父节点）
1,101,0,1|2,10|20,5001,True,True,-1
1,102,1,3,30,5002,True,True,101
```
> 生成的 `.csv` 可直接用 Excel 打开（打开时选 UTF-8 编码）。
**第六步：批量编辑后导入 CSV → Canvas**
1. 用 Excel 修改 `Assets/玩法编辑器.csv`（**不要删除前3行表头**）
2. 保存文件
3. 回到 Unity，点击 **"导入 CSV → Canvas"**
> **注意：导入会清空当前 Canvas 中的所有节点后重建。** 导入后自动根据 `ParentNodeID` 重建连线，`-1` 表示根节点不连线。
---
### 5.3 嵌套节点示例
**CSV 数据：**
```
LevelID,NodeID,NodeLayer,...,ParentNodeID
int,int,int,...,int
（doc行）
1,100,0,...,-1
1,101,1,...,100
1,102,1,...,100
1,103,2,...,101
```
**Canvas 连线结构：**
```
[NodeID:100]（根节点，ParentNodeID=-1）
├── [NodeID:101]（ParentNodeID=100）
│ └── [NodeID:103]（ParentNodeID=101）
└── [NodeID:102]（ParentNodeID=100）
```
---
### 5.4 运行时自动同步（可选）
如需在运行时自动同步，将 `GraphExcelSyncManager` 组件挂到场景中的 GameObject 上：
1. **Add Component → GraphExcelSyncManager**
2. Inspector 中绑定 `Target Graph` 和 `Schema`
之后每次 Graph 触发序列化事件时会自动写入 CSV。
---
## 6. 常见问题
| 问题 | 原因 | 解决方法 |
|------|------|---------|
| 导入后节点全部重叠 | 导入时节点默认位置为 Vector2.zero | 在 Canvas 中手动排布节点位置 |
| CSV 用 Excel 打开乱码 | 编码不一致 | Excel → 数据 → 从文本/CSV 导入 → 选 UTF-8 |
| 导入报错 "CSV file format invalid" | 缺少前3行表头 | 保留 NAME/TYPE/DOC 三行，数据从第4行开始 |
| 点击导出提示"请选择 Graph 和 Schema" | 工具栏拖槽为空 | Graph 和 Schema 两个拖槽都需要赋值 |
| Create 菜单找不到 Gameplay Graph | 正常，菜单已注册 | 右键 → Create → NodeCanvas → Gameplay Graph |
| QA 发现流程卡死 | 可能是配置问题也可能是程序问题 | 先策划自检行为树节点报错，确认非配置问题再提程序单 |