(Docs) feat:添加代码规范文件

This commit is contained in:
m0_75251201
2025-07-09 11:34:01 +08:00
parent 2976c96ed7
commit 11004d5595

112
Docs/spec.md Normal file
View File

@ -0,0 +1,112 @@
# 代码与数据存储规范
## 1. 命名空间规范
所有代码必须位于命名空间 `Cell` 中。例如:
```csharp
namespace Cell
{
// 所有类、接口、枚举等均需定义在此命名空间下
}
```
### 1.1 接口规范
为了实现更方便的帧控制,受时刻影响的代码应选择实现以下接口之一或多个:
- **ITick**:适用于通用逻辑更新。
- **ITickPhysics**:适用于物理相关逻辑更新(使用平稳的物理帧)。
- **ITickUI**:适用于用户界面相关的逻辑更新。
首次启动需要调用Clock.Instance来初始化时钟
#### 1.1.1 接口说明
- **ITick** 和 **ITickPhysics** 受暂停影响。
- **ITickPhysics** 使用系统提供的平稳物理帧进行更新。
- **ITickUI** 不受暂停影响,始终在每一帧更新。
#### 1.1.2 示例代码
```csharp
namespace Cell
{
public class ExampleObject : ITick, ITickPhysics
{
public void Tick()
{
// 更新通用逻辑
}
public void TickPhysics()
{
// 更新物理逻辑
}
}
}
```
---
## 2. 数据存储规范
### 2.1 数据存储格式
参考 RimWorld 的数据存储格式,本体和 Mod 的数据均使用 XML 文件存储,并支持动态加载。
#### 2.1.1 文件夹结构
程序启动时会读取以下两个文件夹中的 XML 文件:
- **Data 文件夹**:存放本体的核心数据。
- **Mods 文件夹**:存放 Mod 提供的扩展数据。
#### 2.1.2 XML 文件根属性规范
XML 文件的根节点必须包含以下两种属性之一:
- **Define**:表示此 XML 文件定义的是一个数据类型。
- **About**:表示此 XML 文件是 Mod 的介绍信息。
- **Translation**:表示此 XML 文件是翻译文件。
#### 2.1.3 示例 XML 文件
##### 定义数据类型 (Define)
```xml
<Define>
<Class1>
<defName>class1</defName>
<label>apple</label>
<variableName>value</variableName>
</Class1>
<Class1>
...
</Class1>
<Class2>
...
<!-- 引用class1 -->
<variableName>class1</variableName>
</Class2>
</Define>
```
##### Mod 介绍 (About)
```xml
<About>
<Author>AuthorName</Author>
<Description>This is a description of the mod.</Description>
</About>
```
##### 翻译文件 (Translation)
```xml
<Translation>
<Class1.label>苹果</Class1.label>
<Key2>Value2 in English</Key2>
</Translation>
```
---
## 3. 动态加载流程
### 3.1 启动时加载
程序启动时,按以下顺序加载数据:
1. **加载 Data 文件夹**:读取并解析核心数据。
2. **加载 Mods 文件夹**:依次读取每个 Mod 的 XML 文件,动态加载 Mod 数据。
#### 3.1.1 加载优先级
由加载列表确定加载优先级