add: dev-spec-coding.md.

Signed-off-by: 秋雨落 <i@rain.cx>

.github/workflows/build-documents.yml

@@ -17,18 +17,15 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
-
     steps:
       - name: Checkout
         uses: actions/checkout@v3
-
       - name: Build
         uses: JetBrains/writerside-github-action@v4
         with:
           instance: ${{ env.INSTANCE }}
           artifact: ${{ env.ARTIFACT }}
           docker-version: ${{ env.DOCKER_VERSION }}
-
       - name: Upload
         uses: actions/upload-artifact@v3
         with:
@@ -57,28 +54,21 @@ jobs:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-
     needs: build
-
     runs-on: ubuntu-latest
-
     steps:
       - name: Download
         uses: actions/download-artifact@v3
         with:
           name: docs
-
       - name: Unzip
         run: unzip -O UTF-8 -qq ${{ env.ARTIFACT }} -d dir
-
       - name: Setup
         uses: actions/configure-pages@v2
-
       - name: Upload
         uses: actions/upload-pages-artifact@v1
         with:
           path: dir
-
       - name: Deploy
         id: deployment
         uses: actions/deploy-pages@v1

Documents/documents.tree

@@ -3,20 +3,31 @@
         SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
 
 <instance-profile id="documents"
-                 name="SinoSeries Developers Document"
-                 start-page="starter-topic.md">
-    <toc-element topic="starter-topic.md"/>
-
-    <toc-element topic="sinocore.md">
-        <toc-element topic="sinocore-block.md">
-            <toc-element topic="sinocore-block-ILootableBlock.md"/>
-            <toc-element topic="sinocore-block-Crop.md"/>
-            <toc-element topic="sinocore-block-CropBlock.md"/>
-            <toc-element topic="sinocore-block-BlockWithBlockEntity.md"/>
-            <toc-element topic="sinocore-block-chest.md"/>
-            <toc-element topic="sinocore-block-BlockLootables.md"/>
-            <toc-element topic="sinocore-block-VoxelShapeHelper.md"/>
+                 name="SinoSeries Document"
+                 start-page="starter.md">
+    <toc-element topic="starter.md"/>
+    <toc-element toc-title="游玩指南">
+        <toc-element topic="playing.md"/>
+    </toc-element>
+    <toc-element toc-title="开发文档">
+        <toc-element toc-title="开发规范">
+            <toc-element topic="dev-spec-coding.md"/>
+        </toc-element>
+        <toc-element toc-title="SinoCore 华夏核心">
+            <toc-element topic="dev-sc.md"/>
+            <toc-element toc-title="方块">
+                <toc-element topic="dev-sc-block-ILootableBlock.md"/>
+                <toc-element topic="dev-sc-block-crops.md"/>
+                <toc-element topic="dev-sc-block-crop-blocks.md"/>
+                <toc-element topic="dev-sc-block-BlockWithBlockEntity.md"/>
+                <toc-element topic="dev-sc-block-chests.md"/>
+            </toc-element>
+            <toc-element toc-title="数据生成"/>
+            <toc-element toc-title="物品"/>
+            <toc-element toc-title="工具类">
+                <toc-element topic="dev-sc-utility-BlockLootables.md"/>
+                <toc-element topic="dev-sc-utility-VoxelShapeHelper.md"/>
+            </toc-element>
         </toc-element>
-        <toc-element topic="sinocore-item.md"/>
     </toc-element>
 </instance-profile>

Documents/topics/dev-sc.md

@@ -0,0 +1,17 @@
+# 华夏核心
+
+华夏核心，华夏系列模组核心代码库。  
+该 Mod 不提供任何影响游戏体验的内容，仅为其他模组提供代码支持。
+
+<!--
+- 方块 - Block
+- 物品与物品栏标签 - Item & CreativeModeTab
+- 流体 - Fluid
+- NBT - 与数据包 NBT & Packet
+- 配方 - Recipe
+- 数据生成 - DataProvider
+- 网络 - Network
+- 界面与 - Gui 绘制
+- 树与木制品 - Tree
+- 其他通用工具
+-->

Documents/topics/dev-spec-coding.md

@@ -0,0 +1,92 @@
+# 代码规范
+
+为规范模组开发过程，编制此文档。  
+2023 年 12 月 20 日修订。
+
+## 命名风格
+
+1. **【强制】** 所有代码中的命名应当使用英文，除了一些专有名词没有英文对应翻译的。  
+   *正例：* `QingGui`（青珪，一种上尖下方的玉质礼器）  
+   *反例：* `ModWuPin`（模组物品）
+
+2. **【强制】** 所有的类命名均使用 PascalCase（又称大驼峰、CapitalCamelCase 或 UpperCamelCase）风格。  
+   *正例：* `ModClass`
+
+3. **【强制】** 所有的接口命名以大写字母 I 开头。  
+   *正例：* `IPlayerCapabilityHolder`
+
+4. **【强制】** 在 API 中对外开放的抽象类命名以单词 Abstract 开头；在实现中的抽象类（不应被使用该 API 的类继承的）以 Base 结尾。  
+   *正例：* `AbstractBlockStateProvider`、`BlockStateProviderBase`  
+   *反例：* `BaseBlockState`
+
+5. **【强制】** 异常类命名以单词 Exception 结尾；测试类命名以要测试的类的名称开始，以单词 Test 结尾。
+
+6. **【强制】** 方法名、参数名、成员变量、局部变量的命名都统一使用 camelCase（又称小驼峰、lowerCamelCase）风格。  
+   *正例：* `paramValue`、`onUse()`、`serverId`
+
+7. **【强制】** 常量命名均使用 MACRO_CASE（又称 CONSTANT_CASE 或 SCREAM_CASE）风格。
+
+8. **【强制】** 枚举类的成员命名同常量命名。
+
+9. **【强制】** 包名统一使用小写，点分隔符之间有且仅有一个英语单词（如果必须要两个及以上单词才能表达完整含义，使用 camelCase）。  
+   *说明：* 若专有名词不是一个英语单词，如模组 ModID、组织名称等，也视为一个单词。  
+   *正例：* `games.moegirl.sinocraft.sinocore`、`cx.rain.mc.icon_at_night`
+
+10. **【强制】** 禁止使用不规范的英文缩写，如果难以找到合适的缩写，请使用完整的名称。  
+    *反例：* `Abstract` 缩写成 `Abs`
+
+11. **【推荐】** 最外层包名采用域名反写的形式，项目所有者最好持有该域名。  
+    *说明：* 可能会用于避免潜在的版权问题。若是非 ASCII 的一级域名，请使用 Punycode 转换，包含横杠（又称连字符，-）的用下划线替代。  
+
+12. **【推荐】** 在常量和变量命名时，表示其取值的性质的单词放在末尾，以增加可读性。  
+    *正例：* `startTime`、`playerList`、`MAX_THREAD_COUNT`  
+    *反例：* `startAt`、`listPlayer`、`MAX_THREADS`
+
+13. **【推荐】** 如果模块、类、接口、方法使用了设计模式，在命名时要体现出具体模式。  
+    *正例：* `StringDecorator`、`NmsFactory`
+
+14. **【强制】** 模组中用于注册游戏内容的类命名以 Mod 或者模组 ID 的缩写开头，后接注册的游戏内容名称（如 Block、Item）。  
+    *正例：* `ModBlocks`、`SCItems`
+
+15. **【强制】** 模组中的游戏内容类，命名应以游戏内容的名称结尾。  
+    *正例：* `KnifeItem`、`StoveBlock`
+
+16. **【强制】** 模组中用于逻辑服务端和逻辑客户端通信的类命名以传输方向（S2C、C2S）开头，以 Packet 结尾。  
+    *正例：* `C2SSaveDrawingPacket`
+
+17. **【强制】** 枚举类的命名以 Enum 结尾。
+
+## 常量定义
+
+1. **【强制】** 使用类型和中括号紧邻的方式（Java 风格）定义数组。  
+   *正例：* `int[] intArray;`  
+   *反例：* `String args[];`
+
+2. **【强制】** 长整数类型的字面量，数值后使用大写的 L ，禁止使用小写的 l。
+   说明：小写 l 在一些字体下容易和数字 1 混淆，造成误解。
+
+3. **【强制】** 浮点数类型的字面量，单精度的数值后面使用大写的 F ，双精度的数值后面不加 D（因为 Java 默认为双精度浮点数）。
+
+4. **【强制】** 当被调用方法的形参为浮点数类型，且实参恰好是整数的时候，不要额外加小数部分，让 Java 自动隐式转换。  
+   *正例：* `Box.shape(1, 1, 1, 15, 15, 15);`  
+   *反例：* `Box.shape(1.0F, 1.0F, 1.0F, 15.0F, 15.0F, 15.0F);`  
+
+5. **【推荐】** 如果变量值仅在一个有限且大小可枚举的固定范围内变化，使用枚举类型定义。
+
+## 代码格式
+
+1. **【强制】** 左花括号前不换行，左花括号后换行；右花括号前换行，右花括号后如果是 else 等代码不换行，否则必须换行。
+
+2. **【强制】** 如果仅有一行代码，也应当用花括号包围。
+
+3. **【强制】** 左圆括号与其右侧的相邻字符之间不加空格，右圆括号与其左侧的相邻字符之间不加空格；右圆括号和左花括号之间要加空格。
+
+4. **【强制】** Java 语言中用于执行控制的保留字（如 if / for / while / switch / do）与左右圆括号之间都必须加空格。
+
+5. **【强制】** 任何二目、三目运算符的左右两侧都要加一个空格。
+
+6. **【强制】** 采用四个空格缩进，禁止使用 Tab 字符缩进。
+
+<!--
+## 项目源代码组织结构
+-->

Documents/topics/playing.md

@@ -0,0 +1,4 @@
+# 游玩指南
+
+Todo.  
+如果在第一个版本发布之前还没写好，请摇 qyl 来原地写文档！

Documents/topics/starter-topic.md → Documents/topics/starter.md

@@ -1,3 +1 @@
 # SinoSeries 华夏系列 Minecraft 模组
-
-Start typing here...