From bcd131105b6d346f8d3569d168818a30174cb955 Mon Sep 17 00:00:00 2001
From: m0_75251201 <m0_75251201@noreply.gitcode.com>
Date: Thu, 10 Jul 2025 20:34:38 +0800
Subject: [PATCH] =?UTF-8?q?(docs)=20feat:=E6=B7=BB=E5=8A=A0=E6=95=B0?=
 =?UTF-8?q?=E6=8D=AE=E5=AE=9A=E4=B9=89=E4=BD=BF=E7=94=A8=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Docs/DefineUse.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 162 insertions(+)
 create mode 100644 Docs/DefineUse.md

diff --git a/Docs/DefineUse.md b/Docs/DefineUse.md
new file mode 100644
index 0000000..b6b7659
--- /dev/null
+++ b/Docs/DefineUse.md
@@ -0,0 +1,162 @@
+### 数据定义使用文档
+
+#### 1. 文件夹结构
+程序在启动时会读取程序所在文件夹中的以下两个文件夹：
+- **Data**：包含游戏的核心数据定义。
+- **Mods**：包含用户或开发者创建的扩展模块。
+
+每个文件夹下的子文件夹被视为一个独立的模块，但模块之间可以互相引用。推荐的文件夹结构如下：
+```
+root/
+├── Data/
+│   ├── About/       # 模块介绍文件
+│   ├── Define/      # 数据定义文件
+│   └── Translation/ # 翻译文件
+└── Mods/
+    ├── Mod1/
+    │   ├── About/
+    │   ├── Define/
+    │   └── Translation/
+    └── Mod2/
+        ├── About/
+        ├── Define/
+        └── Translation/
+```
+
+#### 2. XML 文件类型及用途
+XML 文件根据根属性名分为三种类型：
+- **Define**：用于定义游戏中的数据类型和具体实例。
+- **About**：用于描述模块的基本信息（如名称、版本、依赖关系等）。
+- **Translation**：用于提供多语言支持的翻译内容。
+
+---
+
+### 3. Define 定义
+#### 3.1 根节点
+根节点的属性名为 `Define`，表示这是一个数据定义文件。例如：
+```xml
+<Define>
+    <!-- 数据定义内容 -->
+</Define>
+```
+
+#### 3.2 数据块结构
+每个数据块通常包含以下部分：
+- **defName**：该数据块的唯一标识符（在同一类型中必须唯一）。
+- **字段定义**：通过字段名和值为对应的类变量赋值。
+- **引用**：通过 `defName` 引用其他数据块。
+
+#### 3.3 示例解析
+以下是一个典型的 `Define` 文件示例：
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<Define>
+    <Attributes>
+        <defName>CatGirl</defName>
+        <health>100</health>
+        <speed>1.2</speed>
+        <strength>5</strength>
+    </Attributes>
+
+    <Character>
+        <defName>CatGirl</defName>
+        <label>CatGirl</label>
+        <description>She is a cat girl with agile movements and sharp senses.</description>
+        <attributes>CatGirl</attributes> <!-- 引用 Attributes 类型的数据块 -->
+
+        <drawingOrder_down>CatGirl_down</drawingOrder_down> <!-- 引用 DrawingOrder 类型的数据块 -->
+        <drawingOrder_left>CatGirl_left</drawingOrder_left>
+        <drawingOrder_right>CatGirl_right</drawingOrder_right>
+        <drawingOrder_up>CatGirl_up</drawingOrder_up>
+    </Character>
+
+    <DrawingOrder>
+        <defName>CatGirl_down</defName>
+        <DrawNode name="body">
+            <DrawNode name="head">
+                <DrawNode name="backHair"/>
+                <DrawNode name="ear"/>
+                <DrawNode name="face"/>
+                <DrawNode name="frontHair"/>
+                <DrawNode name="hat"/>
+            </DrawNode>
+            <DrawNode name="clothes"/>
+        </DrawNode>
+    </DrawingOrder>
+</Define>
+```
+
+#### 3.4 加载流程
+1. **索引建立**：程序加载时会依次读取所有 `Define` 文件，并记录每个数据块的 `defName` 和类型。
+2. **引用连接**：在所有数据块加载完成后，程序会根据 `defName` 连接引用关系。
+
+---
+
+### 4. About 定义
+#### 4.1 根节点
+根节点的属性名为 `About`，表示这是一个模块的介绍文件。例如：
+```xml
+<About>
+    <!-- 模块信息 -->
+</About>
+```
+
+#### 4.2 字段说明
+| 字段名       | 描述                                                                 |
+|--------------|----------------------------------------------------------------------|
+| `name`       | 模块名称。                                                           |
+| `description` | 模块的详细描述。                                                     |
+| `version`    | 模块版本号。                                                         |
+| `packID`     | 模块的唯一标识符，用于区分不同模块。                                 |
+| `sort`       | 模块加载顺序配置，包含 `before` 和 `after` 两个子字段，分别指定优先加载的模块和后加载的模块。 |
+
+#### 4.3 示例解析
+以下是一个典型的 `About` 文件示例：
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<About>
+    <name>核心</name>
+    <description>这是游戏的核心模块，除非有完整的代替，否则应该永远作为启动项</description>
+    <version>0.1</version>
+    <packID>core</packID>
+    <sort>
+        <before></before> <!-- 优先于哪些模块加载 -->
+        <after></after>   <!-- 在哪些模块之后加载 -->
+    </sort>
+</About>
+```
+
+---
+
+### 5. Translation 定义
+#### 5.1 根节点
+根节点的属性名为 `Translation`，表示这是一个翻译文件。例如：
+```xml
+<Translation>
+    <!-- 翻译内容 -->
+</Translation>
+```
+
+#### 5.2 字段说明
+翻译文件中的每个字段以点号分隔的形式表示路径，格式为：
+```
+<类型名>.<defName>.<字段名>
+```
+例如：
+```
+Character.CatGirl.label
+```
+
+#### 5.3 示例解析
+以下是一个典型的 `Translation` 文件示例：
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<Translation>
+    <Character.CatGirl.label>猫娘</Character.CatGirl.label>
+    <Character.CatGirl.description>她是一个猫娘，拥有猫的特性和人类的智慧。她的耳朵和尾巴显示了她的猫族血统。</Character.CatGirl.description>
+</Translation>
+```
+