diff --git a/README.md b/README.md index e2552db..dffe372 100644 --- 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) \ No newline at end of file +[开发指南](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 new file mode 100644 index 0000000..abc2a67 --- /dev/null +++ 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 中应写明实际执行的检查，以及尚未验证的部分。