merge upstream
This commit is contained in:
@ -1,35 +1,94 @@
|
||||
# DrawingOrderDef使用文档
|
||||
# XML 渲染层级定义文档
|
||||
|
||||
---
|
||||
## 概述
|
||||
|
||||
## 1. 基本概念
|
||||
本文档介绍如何使用 XML 定义游戏对象的渲染层级结构。通过 `DrawingOrder` 可以创建树形结构的渲染顺序定义，`defName` 用于唯一标识定义，`DrawNode` 则定义了各个渲染节点及其层级关系。
|
||||
|
||||
### 1.1 DrawingOrderDef
|
||||
`DrawingOrderDef` 是用于定义游戏对象树形结构的根节点。它表示整个渲染层级的入口点。
|
||||
|
||||
### 1.2 defName
|
||||
`defName` 是 `DrawingOrderDef` 的子节点，用于指定当前渲染层级结构的唯一引用名称。这个名称可以在其他地方（如脚本或配置文件）中被引用。
|
||||
|
||||
### 1.3 DrawNodeDef
|
||||
`DrawNodeDef` 是定义渲染层级中的节点元素。每个 `DrawNodeDef` 可以包含子节点，形成树形结构。其属性包括：
|
||||
- **name**：节点的名称，用于标识该节点。
|
||||
- **type**：可选属性，用于指定节点的类型。目前支持的类型有：
|
||||
- `image`：表示一个静态图像。
|
||||
- `animation`：表示一个动画序列。
|
||||
|
||||
---
|
||||
|
||||
## 2. 示例解析
|
||||
|
||||
以下是一个完整的 XML 示例及其解析：
|
||||
## 基本结构
|
||||
|
||||
```xml
|
||||
<DrawingOrderDef>
|
||||
<defName>CatGirl</defName>
|
||||
<defName>唯一标识名称</defName>
|
||||
<DrawNodeDef name="根节点名称" [属性]>
|
||||
<!-- 子节点定义 -->
|
||||
</DrawNodeDef>
|
||||
</DrawingOrderDef>
|
||||
```
|
||||
|
||||
## 元素说明
|
||||
|
||||
### DrawingOrderDef
|
||||
- 根元素，表示一个完整的渲染层级定义
|
||||
- 必须包含一个 `defName` 子元素和至少一个 `DrawNodeDef` 子元素
|
||||
|
||||
### defName
|
||||
- 定义该渲染层级的唯一标识名称
|
||||
- 在其他系统中可以通过此名称引用该定义
|
||||
|
||||
### DrawNodeDef
|
||||
- 定义一个渲染节点
|
||||
- 可以包含其他 `DrawNodeDef` 作为子节点，形成树形结构
|
||||
- 属性：
|
||||
- `name`：节点名称（必需）
|
||||
- `type`：节点类型（可选，默认为"image"）
|
||||
- `image`：静态图片
|
||||
- `animation`：动画序列
|
||||
- `position`：节点位置偏移（可选，格式为"x,y"）
|
||||
- `FPS`：动画播放速度（仅对动画类型有效，可选）
|
||||
|
||||
## 节点类型详解
|
||||
|
||||
### 1. 静态图片节点 (type="image")
|
||||
- 表示一个静态的图片元素
|
||||
- 不需要额外属性（除基本属性外）
|
||||
|
||||
### 2. 动画节点 (type="animation")
|
||||
- 表示一个动画序列
|
||||
- 可选属性：
|
||||
- `FPS`：定义动画播放速度（帧/秒）
|
||||
|
||||
## 材质资源组织
|
||||
|
||||
### 自动路径匹配
|
||||
1. 在定义包下创建资源文件夹结构：
|
||||
```
|
||||
包目录/
|
||||
└── Resource/
|
||||
└── 类型名/
|
||||
└── 定义名/
|
||||
├── 节点1名称/
|
||||
│ ├── down.png
|
||||
│ ├── left.png
|
||||
│ └── ...
|
||||
├── 节点2名称/
|
||||
│ ├── down.png
|
||||
│ └── ...
|
||||
└── ...
|
||||
```
|
||||
|
||||
2. 对于动画节点：
|
||||
```
|
||||
节点名称/
|
||||
├── down_1.png
|
||||
├── down_2.png
|
||||
├── down_3.png
|
||||
├── left_1.png
|
||||
├── left_2.png
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 手动路径指定
|
||||
- 可以通过 `CharacterDef` 手动指定资源路径（本文档不详细介绍）
|
||||
|
||||
## 示例解析
|
||||
|
||||
```xml
|
||||
<DrawingOrderDef>
|
||||
<defName>CatGirl_down</defName>
|
||||
<DrawNodeDef name="body">
|
||||
<DrawNodeDef name="head">
|
||||
<DrawNodeDef name="backHair"/>
|
||||
<DrawNodeDef name="ear"/>
|
||||
<DrawNodeDef name="ear" type="animation" FPS="1"/>
|
||||
<DrawNodeDef name="face"/>
|
||||
<DrawNodeDef name="frontHair"/>
|
||||
<DrawNodeDef name="hat"/>
|
||||
@ -39,52 +98,68 @@
|
||||
</DrawingOrderDef>
|
||||
```
|
||||
|
||||
### 2.1 结构说明
|
||||
1. **根节点**：`DrawingOrderDef` 表示此角色的渲染树
|
||||
2. **唯一标识**：`defName` 节点指定了当前渲染层级结构的名称为 `CatGirl`。
|
||||
3. **渲染层级**：
|
||||
- `body` 是顶层节点，表示角色的身体部分。
|
||||
- `head` 是 `body` 的子节点，表示头部。
|
||||
- `backHair`、`ear`、`face`、`frontHair` 和 `hat` 是 `head` 的子节点，分别表示后发、耳朵、脸部、前发和帽子。
|
||||
- `clothes` 是 `body` 的另一个子节点，表示角色的衣服。
|
||||
### 结构说明
|
||||
1. 定义了一个名为 "CatGirl_down" 的渲染层级
|
||||
2. 根节点为 "body"
|
||||
3. "body" 包含两个子节点：
|
||||
- "head"：头部节点，包含多个子部件
|
||||
- "backHair"：后发
|
||||
- "ear"：耳朵（动画类型，1 FPS）
|
||||
- "face"：脸部
|
||||
- "frontHair"：前发
|
||||
- "hat"：帽子
|
||||
- "clothes"：服装
|
||||
|
||||
### 2.2 渲染顺序
|
||||
在渲染时，系统会按照 XML 中定义的树形结构依次绘制每个节点。例如，在上述例子中，渲染顺序为：
|
||||
1. `body`
|
||||
- `head`
|
||||
- `backHair`
|
||||
- `ear`
|
||||
- `face`
|
||||
- `frontHair`
|
||||
- `hat`
|
||||
- `clothes`
|
||||
|
||||
这种顺序确保了层次分明的渲染效果，例如，头发和帽子会覆盖在脸部之上，衣服则位于身体外部。
|
||||
|
||||
---
|
||||
|
||||
## 3. 扩展功能
|
||||
|
||||
### 3.1 指定节点类型
|
||||
可以通过 `type` 属性为节点指定具体的类型。例如：
|
||||
|
||||
```xml
|
||||
<DrawNodeDef name="background" type="image"/>
|
||||
<DrawNodeDef name="walk" type="animation"/>
|
||||
### 对应的资源文件夹结构
|
||||
```
|
||||
Resource/
|
||||
└── Character/
|
||||
└── CatGirl/
|
||||
├── body/
|
||||
│ └── down.png
|
||||
├── head/
|
||||
│ └── down.png
|
||||
├── backHair/
|
||||
│ └── down.png
|
||||
├── ear/
|
||||
│ ├── down_1.png
|
||||
│ ├── down_2.png
|
||||
│ └── ...
|
||||
├── face/
|
||||
│ └── down.png
|
||||
├── frontHair/
|
||||
│ └── down.png
|
||||
├── hat/
|
||||
│ └── down.png
|
||||
└── clothes/
|
||||
└── down.png
|
||||
```
|
||||
|
||||
- 如果 `type="image"`，则表示该节点是一个静态图像。
|
||||
- 如果 `type="animation"`，则表示该节点是一个动画序列。
|
||||
## 高级用法
|
||||
|
||||
默认为image
|
||||
### 位置偏移
|
||||
可以为节点添加 `position` 属性来定义相对偏移：
|
||||
|
||||
### 3.2 动态引用
|
||||
通过 `defName`，可以将定义好的渲染层级结构动态引用到其他地方。例如，如果某个脚本需要加载 `CatGirl` 的渲染结构，可以直接通过 `defName` 引用。
|
||||
```xml
|
||||
<DrawNodeDef name="weapon" position="10,-5">
|
||||
<DrawNodeDef name="effect" position="5,0" type="animation" FPS="12"/>
|
||||
</DrawNodeDef>
|
||||
```
|
||||
|
||||
---
|
||||
### 混合类型
|
||||
可以在同一个层级中混合使用静态和动画节点：
|
||||
|
||||
## 4. 注意事项
|
||||
```xml
|
||||
<DrawNodeDef name="character">
|
||||
<DrawNodeDef name="body"/>
|
||||
<DrawNodeDef name="weapon" type="animation" FPS="8"/>
|
||||
<DrawNodeDef name="aura" type="animation" FPS="24"/>
|
||||
</DrawNodeDef>
|
||||
```
|
||||
|
||||
1. **节点命名唯一性**：在同一层级中，节点的 `name` 属性应保持唯一，以避免冲突。
|
||||
2. **类型匹配**：如果指定了 `type` 属性，确保实际内容与类型一致（如 `image` 对应静态图片资源，`animation` 对应动画资源）。
|
||||
3. **嵌套深度**：虽然理论上可以无限嵌套，但建议控制嵌套深度，以提高性能和可维护性。
|
||||
## 注意事项
|
||||
|
||||
1. 节点名称在同一层级中必须唯一
|
||||
2. 动画节点的 FPS 值应大于 0
|
||||
3. 资源文件的命名必须严格匹配节点名称和朝向
|
||||
4. 渲染顺序由 XML 中的定义顺序决定（先定义的先渲染，在底层）
|
||||
Reference in New Issue
Block a user