cuccuc377-dev · Oct 22, 2026
diff --git a/README.md b/README.md
@@ -1,12 +1,124 @@
-# Wild Wind Modules 原野之风模块包
+# Wild Wind Modules · 原野之风模块包
 
-### Module List 模块列表
+面向 Minecraft NeoForge 的模块化模组项目，围绕木材、植物、世界生成和制箭玩法扩展原版内容。
 
-| name |         note         | ch name |  note   |
-|:----:|:--------------------:|:-------:|:-------:|
-| hfas |    Wild Wind HFAS    |       | 原野之风函数库 |
-| deco | Wild Wind Decoration |   装饰    | 原野之风装饰库 |
-| adv  | Wind Wind Adventure  |   冒险    | 原野之风冒险库 |
-| vpp  | Wild Wind Vanilla++  |  原版修饰   | 原野之风原版库 |
+> 当前说明对应 `26.1` 分支。项目处于开发阶段，目前仅启用 **HFAS（`ww_hfas`）**；下文区分源码中已有的实现与尚未完成的玩法，具体游戏表现仍需运行验证。
 
-[CHANGES](./CHANGE_LOG.MD)
+[开发指南](docs/DEVELOPMENT.md) · [历史变更](CHANGE_LOG.MD) · [问题反馈](https://github.com/Polari-Stars-MC/WildWindModule/issues) · [许可证](LICENSE)
+
+## 版本与环境
+
+| 项目 | 当前配置 |
+| --- | --- |
+| Minecraft | `26.1.2`（依赖范围为精确版本 `[26.1.2]`） |
+| 模组加载器 | NeoForge `26.1.2.10-beta` |
+| Java 开发工具链 | JDK `25` |
+| Gradle Wrapper | `9.4.1` |
+| 模组版本 | `1.0.0`（构建配置值） |
+| HFAS 模组 ID / 资源命名空间 | `ww_hfas` |
+
+版本以 [gradle.properties](gradle.properties) 和 [构建脚本](build.gradle.kts) 为准。`1.0.0` 是源码中的版本号，不代表已经发布稳定版。
+
+## 模块规划
+
+| 模块 | 名称 | 当前分支状态 |
+| --- | --- | --- |
+| `hfas` | Wild Wind HFAS | 已接入 Gradle，包含木材、植物、世界生成及制箭系统基础代码 |
+| `deco` | Wild Wind Decoration · 装饰 | 旧版模块规划，尚未在当前分支启用 |
+| `adv` | Wild Wind Adventure · 冒险 | 旧版模块规划，尚未在当前分支启用 |
+| `vpp` | Wild Wind Vanilla++ · 原版修饰 | 旧版模块规划，尚未在当前分支启用 |
+
+模块启用列表见 [settings.gradle.kts](settings.gradle.kts)。
+
+## HFAS 内容
+
+### 木材与植物
+
+源码已注册三组木质方块：
+
+| 木材 | 注册内容 | 树木相关实现 |
+| --- | --- | --- |
+| 焚烬木 `blaze` | 15 种方块 | 独立树叶、树苗；配置在下界废土生成 |
+| 灵焰木 `soul` | 15 种方块 | 独立树叶、树苗；配置在灵魂沙峡谷生成 |
+| 杜鹃木 `azalea` | 13 种方块 | 复用原版杜鹃植物与树叶；配置替换繁茂洞穴的原版杜鹃树生成 |
+
+三组木材均包含原木、木头、去皮原木、去皮木头、木板、楼梯、台阶、栅栏、栅栏门、门、活板门、压力板和按钮。焚烬木、灵焰木另有树叶和树苗。
+
+此外已注册焦灰草方块、焦土、焦灰草丛、焦灰枝条、仙人球，并实现木材去皮映射、部分木质物品的燃料处理，以及向原版创造模式分类添加木材的逻辑。杜鹃施加骨粉的行为通过 Mixin 接入自定义树木生成。
+
+### 制箭系统（开发中）
+
+目前包含自定义制箭台方块、方块实体、菜单、箭羽／箭杆／箭头枚举和箭矢数据组件。客户端界面与实际合成流程尚未完成，箭矢配方生成方法仍为空；当前不能视作完整可玩的制箭系统。
+
+模型、语言、标签、掉落表和世界生成数据由数据生成器输出；从源码构建前请阅读[开发指南](docs/DEVELOPMENT.md)。纹理与注册 ID 的一致性也仍需整理。
+
+## 安装与配置
+
+取得经过验证、与上述 Minecraft / NeoForge 版本匹配的模组 JAR 后，将其放入对应实例的 `mods/` 目录。从源码生成 JAR 的步骤见下方。当前开发状态与待完善项见[开发指南](docs/DEVELOPMENT.md#待完善事项)。
+
+HFAS 注册了一个 COMMON 配置项：
+
+| 配置键 | 默认值 | 作用 |
+| --- | --- | --- |
+| `worldgen.replaceVanillaFletchingTable` | `true` | 启用服务端原版制箭台替换逻辑 |
+
+替换发生在方块放置事件及区块加载时。**已有存档中加载的区块也会受影响**：当前区块扫描从世界最低建造高度至固定 `Y=200`，将其中的原版制箭台替换为模组制箭台。关闭配置只会停止后续替换，不会自动恢复已经替换的方块。由于制箭流程尚未完成，测试前请结合这一行为选择配置。
+
+## 从源码开始
+
+准备 JDK 25，在仓库根目录执行。首次运行需要联网下载 Gradle、插件与游戏依赖。
+
+```powershell
+# Windows PowerShell
+git clone --branch 26.1 https://github.com/Polari-Stars-MC/WildWindModule.git
+cd WildWindModule
+.\gradlew.bat :hfas:runClientData
+.\gradlew.bat :hfas:runServerData
+.\gradlew.bat build
+```
+
+```bash
+# Linux / macOS
+git clone --branch 26.1 https://github.com/Polari-Stars-MC/WildWindModule.git
+cd WildWindModule
+chmod +x gradlew
+./gradlew :hfas:runClientData
+./gradlew :hfas:runServerData
+./gradlew build
+```
+
+数据生成成功后再构建；若生成任务报错，请先处理报错，不要把缺少生成资源的 JAR 当作完整发行包。当前构建脚本未将数据生成任务自动接入 `build`。
+
+HFAS 构建产物位于 `modules/hfas/build/libs/`，按当前配置命名为 `ww_hfas-1.0.0.jar`。开发客户端可通过 `:hfas:runClient` 启动。
+
+## 项目结构
+
+```text
+WildWindModule/
+├── src/
+│   ├── hfas/
+│   │   ├── java/                 # HFAS 注册、玩法、配置与数据生成代码
+│   │   └── resources/            # 纹理、Blockbench 源文件、Mixin 配置等
+│   └── templates/                # 各模块共用的模组元数据模板
+├── modules/hfas/                # Gradle 配置时创建的子项目目录
+│   └── build/                   # HFAS JAR、生成元数据和开发运行目录
+├── build/generated/hfas/        # 数据生成输出（client/、server/）
+├── docs/DEVELOPMENT.md           # 开发命令、源码导航与待完善项
+├── .github/workflows/build.yml  # GitHub Actions 构建流程
+├── build.gradle.kts             # 共用构建配置与模块任务
+├── settings.gradle.kts          # 模块启用列表与项目目录映射
+├── gradle.properties            # 版本、工具与模组属性
+└── CHANGE_LOG.MD                # 历史变更记录
+```
+
+`modules/hfas/` 是 Gradle 子项目目录，实际源码集中在 `src/hfas/`。生成目录不纳入 Git；不要直接修改其中的文件，修改对应的数据生成器后重新生成。
+
+## 参与开发
+
+欢迎通过 Issue 反馈问题、讨论功能，并通过 Pull Request 提交修改。提交前请阅读[开发指南](docs/DEVELOPMENT.md)，注明目标分支、对应 Minecraft / NeoForge 版本、复现步骤及验证结果。历史记录见 [CHANGE_LOG.MD](CHANGE_LOG.MD)，当前实现状态以本分支源码为准。
+
+## 许可证
+
+仓库 [LICENSE](LICENSE) 声明采用分项许可：源码使用 [GPL-3.0-only](LICENSE_CODE)，资源、文档和配置等非代码内容使用 [CC-BY-SA-4.0](LICENSE_ASSETS)。具体条款请阅读对应文件。
+
+当前 `gradle.properties` 中的 `modLicense` 仍为 `All Rights Reserved`，与上述仓库声明存在差异，需维护者统一元数据。
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
@@ -0,0 +1,81 @@
+# 开发指南
+
+本指南对应 `26.1` 分支。项目介绍、版本与模块状态见 [README](../README.md)。
+
+## 环境与构建
+
+- 使用 JDK 25；`build.gradle.kts` 为模块设置了 Java 25 工具链。
+- 使用仓库自带的 Gradle Wrapper，无需单独安装 Gradle。
+- Gradle 配置了 Foojay 工具链解析器，但首次依赖下载仍需要可用网络。
+- 当前只有 `hfas` 子项目，模组 ID 为 `ww_hfas`。
+
+以下命令均在仓库根目录执行，Windows 使用 `.\gradlew.bat`，Linux / macOS 使用 `./gradlew`：
+
+| 操作 | Windows PowerShell 命令 |
+| --- | --- |
+| 查看模块任务 | `.\gradlew.bat :hfas:tasks --all` |
+| 生成客户端数据 | `.\gradlew.bat :hfas:runClientData` |
+| 生成服务端数据 | `.\gradlew.bat :hfas:runServerData` |
+| 构建项目 | `.\gradlew.bat build` |
+| 启动开发客户端 | `.\gradlew.bat :hfas:runClient` |
+| 启动开发服务端 | `.\gradlew.bat :hfas:runServer` |
+| 清理构建输出 | `.\gradlew.bat clean` |
+
+这些运行入口来自构建脚本中的 `client`、`server`、`clientData`、`serverData` 配置。依赖解析成功是运行任务的前提。
+
+### 数据生成顺序
+
+首次构建、清理后构建，或修改数据生成代码后，按顺序执行客户端数据生成、服务端数据生成、`build`。开发运行前也应先生成所需资源。任一步失败时，先解决失败原因再继续。
+
+| 输出目录 | 来源与内容 |
+| --- | --- |
+| `build/generated/hfas/client/` | 模型、`en_us` / `zh_cn` 语言文件 |
+| `build/generated/hfas/server/` | 方块与物品标签、掉落表、世界生成、数据映射、配方生成入口 |
+| `modules/hfas/build/generated/sources/modMetadata/` | 从 `src/templates/` 展开的模组元数据 |
+| `modules/hfas/build/libs/` | 构建的 JAR |
+| `modules/hfas/build/runs/hfas/` | 开发客户端、服务端及数据生成的运行目录 |
+
+生成资源被加入模块的资源集，但 `build` 不会自动先运行数据生成，`clean` 会删除生成结果。生成器是否输出了完整内容还取决于其具体实现，例如当前箭矢配方生成方法为空。
+
+当前 CI 使用 JDK 25 执行 `./gradlew build`，没有显式执行两类数据生成任务，因此构建通过本身不能证明生成资源完整或玩法可用。`.bbmodel` 文件作为建模源文件保存在源码资源目录中，打包时被排除。
+
+## 源码导航
+
+HFAS Java 包根目录为 `src/hfas/java/org/polaris2023/wildwind/hfas/`。
+
+| 入口 / 目录 | 职责 |
+| --- | --- |
+| `HFASMod.java` | 模组入口，注册方块、物品、菜单、方块实体、组件与配置 |
+| `block/`、`block/entity/` | 方块及制箭台方块实体 |
+| `menu/` | 制箭台菜单与槽位逻辑 |
+| `arrow/`、`component/` | 箭矢部件定义与数据组件序列化 |
+| `config/` | COMMON 配置规范 |
+| `event/` | 制箭台替换及燃料事件 |
+| `groups/` | 向原版创造模式分类插入物品 |
+| `worldgen/` | 树木、放置特征与生物群系修改器 |
+| `mixin/` | 杜鹃骨粉生长行为修改 |
+| `datagen/` | 客户端 / 服务端数据生成入口和各类 Provider |
+
+修改资源时注意命名空间 `ww_hfas`，同时核对注册 ID、模型纹理引用、语言键、标签与配方。`gradle.properties` 中的 `modId=wild_wind` 没有直接作为 HFAS 的最终 ID；当前构建脚本通过根项目名 `ww` 与模块名 `hfas` 组合得到 `ww_hfas`。
+
+## 模块维护
+
+当前构建约定将 `src/<模块名>/java/` 和 `src/<模块名>/resources/` 接入相应子项目，`modules/<模块名>/` 在配置阶段创建。新增模块需要同步修改 `settings.gradle.kts` 的启用列表，并核对模组入口、资源命名空间、Mixin 配置与共用元数据模板。仅在 README 增加模块名称不会生成可用模块。
+
+## 待完善事项
+
+以下项目根据当前源码整理，是后续开发清单，不代表已完成功能：
+
+- **制箭交互**：补齐客户端 Screen 与注册，核对菜单和方块实体的容器连接、槽位数量及快捷移动索引；当前制箭台没有注册对应方块物品。
+- **箭矢玩法**：实现配方生成及实际合成流程，并验证部件数据的保存、网络同步与效果行为。
+- **资源一致性**：方块注册使用 `blaze_*` / `soul_*`，现有相关纹理使用 `cinder_*` / `ember_*`；需统一引用与文件命名。资源中的船、告示牌贴图尚不对应已注册的玩法内容。
+- **数据生成与打包**：验证两类数据生成任务，补齐资源后考虑将其接入打包流程及 CI，避免发布缺少模型、语言或世界生成 JSON 的产物。
+- **存档行为**：验证制箭台对旧区块的替换逻辑、扫描范围与性能；README 已记录默认开启和不会自动回滚的行为。
+- **元数据**：替换模组描述模板中的 `Example mod description.`，并由维护者统一 `modLicense` 与仓库许可证声明。
+- **其他模块**：`deco`、`adv`、`vpp` 尚未加入当前分支的 Gradle 模块列表，需要分别实现后再更新状态。
+
+## 提交前验证
+
+文档改动应核对相对链接、命令、版本和模块状态，并执行 `git diff --check`。
+
+涉及代码或资源的改动，应按影响范围运行数据生成与构建，再进行对应客户端或服务端验证；世界生成与制箭台替换需要同时关注新世界及已有区块。Pull Request 中应写明实际执行的检查，以及尚未验证的部分。