HyTool变体

---

HyToolVariants 为游戏工具添加了随机属性变体，使每次合成或战利品获得的镐/斧/铲/锄/剪刀都能随机获得不同的挖掘或辅助加成。变体数据存储在每个物品上，并在交易、存储和服务器重启后保持不变。

---

声明： 此模组仍在开发中！请在 CurseForge 项目页面 或 Discord 报告 Bug 或功能请求。

报告问题时，请附上： mods/HyToolVariants/config.json5、来自 mods/HyToolVariants/Languages/ 的语言文件（如有修改），以及相关的服务器日志片段。在配置中（或通过 /htv 菜单）启用 debug 以获取详细日志；带时间戳的调试日志文件将写入 mods/HyToolVariants/Logs/debug_YYYY-MM-DD_HH-mm-ss.log。默认禁用调试模式。

---

✅ 主要功能

• 每把工具独立判定 — 同一把镐根据其变体可能更强或更弱。
• 持久化物品数据 — 变体数据存储在物品堆（BSON 元数据）上。
• 仅影响工具 — 变体适用于镐、斧、铲、锄和剪刀（变体具有对应的类别标签）。
• 仅限矿石的连锁挖掘 — VeinMining 仅破坏相连的矿石方块（等级控制最大方块数）。
• 夜视 — 持有带有 Night Vision 变体的工具时，通过 PostFx 和可选的 动态光源（可在配置中调节）使场景变亮。默认阈值 0.0，因此典型的变体值（通常在 0.80–1.20）始终满足条件；如需火炬类型的最大半径，可设置 nightVisionLightRadius: -1。
• 游戏内配置菜单 — 使用 /htv 或 /htv menu 打开。可切换启用状态、调试日志、性能模式、掉落倍率、黑名单等；更改语言；无需编辑文件即可保存或重新加载配置。UI 和状态消息已翻译为支持的语言。
• 调试日志生成 — 启用调试后，会在 mods/HyToolVariants/Logs/ 下创建带时间戳的日志文件，用于故障排除（日志记录是异步的）。
• 工具提示中的变体评级 — 当安装了 DynamicTooltipsLib（例如 1.5.x）时，工具提示会首先显示 5 星评级 和 百分比。此依赖为可选；未安装时模组仍可正常运行。
• 经验值整合 — ExpBoost 可与 RPGLeveling 整合，在每次破坏方块时给予经验值（如果可用）。

---

✨ 工具变体（亮点）

镐：

• Reach — 持有工具时增加方块交互范围（如果引擎状态路径支持）。
• Mining Speed — 挖掘性能倍率（在可用时同步元数据/状态）。
• Branch Mine — 在被破坏的方块后方破坏一条短直线上的额外方块。
• Strip Mine — 沿着视线方向进行线性挖掘。
• Vein Mining — 仅对相连的矿石进行泛洪填充式连锁破坏（每个等级的可配置矿石通配符）。
• Ore Yield — 类时运效果的额外矿石掉落缩放。
• Ore Sense — 破坏方块时类似探矿的反馈（仅限镐）。
• Auto Smelt — 将原始矿石掉落物冶炼成锭的几率。

斧：

• Tree Feller — 破坏与配置的木材 ID 通配符匹配的相连原木。
• Lumberjack — 从原木中额外掉落木头/原木。

铲：

• Branch Dig — 破坏可挖掘方块的一个 3×3 面（根据配置）。

锄：

• Gardener — 从作物方块中额外掉落作物/植物。
• Branch Tiller — 更大面积地耕耘土壤（根据配置）。

所有工具（如果成功随机到）：

• Durability / Unbreaking / Efficiency / Movement Speed / Night Vision / Exp Boost — 实用及被动效果；Night Vision 使用客户端 PostFx + 可选动态光源（参见配置键 nightVision*）。

剪刀：

• Shear Speed — 当此变体出现时加快剪刀速度（仅剪刀类别）。

---

📊 默认变体池和随机规则（variantPool）

• 每件符合条件的工具会从池中随机获得 variantCount 个属性（每件物品默认 0–3 个）。权重和倍率范围在 config.json5 中。
• category 会过滤掉不匹配的工具类型属性（例如，仅用于镐的属性永远不会出现在锄上）。

属性 ID	UI 标签	类别
Reach	方块范围	（任何工具）
BranchMine	分支挖掘	PICKAXE_ONLY
MiningSpeed	挖掘速度	PICKAXE_ONLY
StripMine	条形挖掘	PICKAXE_ONLY
OreYield	时运	PICKAXE_ONLY
OreSense	矿石感知	PICKAXE_ONLY
AutoSmelt	自动冶炼几率	PICKAXE_ONLY
TreeFeller	伐木工	HATCHET_ONLY
Lumberjack	伐木者	HATCHET_ONLY
BranchDig	分支挖掘	SHOVEL_ONLY
Gardener	园艺师	HOE_ONLY
BranchTiller	分支耕耘	HOE_ONLY
ShearSpeed	剪切速度	SHEARS_ONLY
DurabilityBonus	耐久	（任何工具）
Unbreaking	经验修复	（任何工具）
Efficiency	效率	（任何工具）
MovementSpeed	移动速度	（任何工具）
NightVision	夜视	（任何工具）
ExpBoost	经验加成	（任何工具）

工具特殊效果（与 multId 分开；参见配置中的 toolSpecialEffects）：

效果 ID	标签	默认说明
VeinMining	连锁挖掘	镐（*Pickaxe* 通配符）；仅矿石的连锁破坏；等级/最大方块数/矿石通配符可配置

---

⚙️ 配置与文件（服务器管理员）

路径相对于服务器工作目录（包含 mods/ 的文件夹）。

路径	用途
mods/HyToolVariants/config.json5	主配置文件 — JSON5 格式（支持注释、尾逗号）。如果缺失，会从 JAR 默认创建。可手动编辑或通过 /htv UI 操作（需要权限）。/htv reload 无需重启即可从磁盘重新加载。
mods/HyToolVariants/Languages/{code}.json5	每种语言的 UI/工具提示字符串。在主配置或菜单中设置 language: "xx"。文件缺失时会从 JAR 中提取附带语言包。
mods/HyToolVariants/Logs/debug_YYYY-MM-DD_HH-mm-ss.log	调试日志 — 当 debug: true 时创建（异步；每次服务器启动生成一个文件；不会自动删除）。

JAR / 资源包内部自带文件（除非重新打包，否则不要编辑）：默认的 HyToolVariants/config.json5（以及回退用的 HyToolVariants/config/HyToolVariants.json5）；UI 布局 Common/UI/Custom/HyToolVariants/HwvConfig.ui。插件声明了 IncludesAssetPack: true。

旧版迁移 — 如果上述路径缺失，模组可能会从以下位置复制：mods/HyToolVariants_HyToolVariants/config.json5、插件数据 config/HyToolVariants.json5、数据目录下的 HyToolVariants/config.json5 或 mods/HyToolVariants/config/HyToolVariants.json5。

物品元数据 — 变体 BSON 存储在键 metaRoot 下（默认为 hyweaponvariants 以保持兼容性）。

夜视键 — nightVisionBloomIntensity、nightVisionBloomPower、nightVisionThreshold（默认 0.0）、nightVisionLightRadius / RGB（0 = 玩家无动态光源；-1 = 最大半径 / 火炬风格）。如果许多工具上的夜视效果不生效，请确保 nightVisionThreshold: 0.0。

---

🌐 支持的语言

工具提示和 UI 字符串可翻译。在 config.json5 中设置 language: "xx" 或通过 /htv 菜单更改。语言文件位于 mods/HyToolVariants/Languages/。

代码	语言
en	English
de	德国 (Deutsch)
cs	捷克 (čeština)
uk	乌克兰 (українська)
fr	法国 (français)
es	西班牙 (español)
pl	波兰 (polski)
ru	俄罗斯 (русский)
pt	葡萄牙 (português)
it	意大利 (italiano)

---

📋 命令 （仅限玩家使用 — 此版本中控制台不可用）

基础命令： /htv — 别名 /hytoolvariants（功能相同）。

用法	别名	功能说明
/htv （无参数）	—	打开配置 UI（需要 help 和 menu 权限 — 见下文）。
/htv help	/htv ?	帮助文本和版本号。
/htv version	/htv ver、/htv v	模组版本字符串。
/htv reload	—	从磁盘重新加载 mods/HyToolVariants/config.json5（无需重启）。
/htv menu	/htv ui	打开配置 UI。
/htv reroll	/htv rr	手持符合条件的工具 — 移除当前变体并重新随机生成。
/htv apply	/htv force	手持工具 — 如果变体缺失且符合条件，强制应用变体。
/htv dump	—	手持物品 — 在聊天中打印变体元数据和调试信息。
/htv rolltest	/htv rt	管理员/诊断：批量 模拟 随机变体（可选 [count] [itemId]）；不会创建真实物品。代码中的默认物品 ID 为武器示例 — 请将 itemId 设置为你的镐 ID 以进行工具相关的检查。

🔐 权限 （LuckPerms / 任何实现 Player.hasPermission(String) 的插件）

权限字符串使用旧版前缀 hyweaponvariants.command.*（与旧的 HyWeaponVariants 包同类 — 这是为了兼容现有权限文件而有意为之）。

权限节点	允许的指令
hyweaponvariants.command.help	/htv 无参数（首次检查）、/htv help、/htv version
hyweaponvariants.command.menu	打开配置 UI（/htv、/htv menu、/htv ui）
hyweaponvariants.command.reload	/htv reload
hyweaponvariants.command.reroll	/htv reroll
hyweaponvariants.command.apply	/htv apply、/htv force
hyweaponvariants.command.dump	/htv dump、/htv rolltest
hyweaponvariants.command.edit	游戏内 UI 中执行保存或更改磁盘上持久化配置的按钮

没有权限插件（玩家没有 hasPermission 方法）：所有人都可以通过简单的 help 检查。更改配置、打开菜单、修改手持物品或输出调试信息的命令需要 管理员 权限（如果存在 isOp() 方法）；否则这些操作会被拒绝。

权限配置示例（LuckPerms 或类似插件） — 不由本模组强制，仅供参考：

• 所有玩家： hyweaponvariants.command.help（读取帮助/版本）。
• 工作人员/建筑师： 添加 hyweaponvariants.command.menu（打开 UI）以及可选的 .edit（保存切换选项）。
• 管理员： 添加 hyweaponvariants.command.reload、.reroll、.apply、.dump（以及 .edit 如果未添加）。或者向单个用户组授予 hyweaponvariants.command.*。

与其他战斗模组的共存 — 在 config.json5 中，disableCombatSystemsWhenHyArmourVariantsPresent 和 disableCombatSystemsWhenHyWeaponVariantsPresent（默认 true）允许 HyToolVariants 在这些模组安装时交出武器攻击处理；工具行为（破坏方块、耐久、被动效果）仍由 HyToolVariants 处理。

📦 可选依赖 （manifest 中声明）

• DynamicTooltipsLib (org.herolias:DynamicTooltipsLib) — 可选；提供更丰富的工具提示。未安装时模组仍可运行；工具提示会更简单。
• HyWeaponVariants — 可选；当此模组存在时，你可以通过配置将攻击处理移交给该模组使两者共存。

其他整合（例如用于 Exp Boost 的 RPGLeveling、HyArmourVariants）会在运行时检测 — 非硬性依赖。

---

🛡️ 技术说明

构建时考虑了更新韧性：安全的反射和后备方案、元数据版本管理、稳定的指纹识别。工具变体按属性 id 存储，因此未来属性重排序不太可能破坏旧物品。

---

🔧 更新后插件不显示/不加载

如果更新（或回滚/重装）后游戏未识别到模组，请尝试：

1. 移除模组 — 从 mods 文件夹中删除 HyToolVariants jar 文件。
2. 清除模组数据 — 删除 mods/HyToolVariants 文件夹（配置和语言文件）。
3. 重启 — 重启游戏/服务器。
4. 重新安装 — 放回 HyToolVariants jar 文件并再次启动。

如果仍未显示，请检查服务器/客户端日志中是否有提及 HyToolVariants 的错误。如果配置文件或语言文件缺失，模组会回退至默认设置。

---

📝 说明

• 掉落和经验值可能因原版 RNG 和配置倍率而变化 — 请比较多次连锁挖掘的平均值。
• 更新日志 — Curseforge_Changelog.md 列出了版本历史、变体表格、指令、权限和配置文件布局；## [version] 标题与 gradle.properties 中的 version 匹配（例如 0.0.1BETA）。

📜 兼容性

• DynamicTooltipsLib — 可选；使用公共工具提示提供者 API。其他模组的已知问题（例如 Soft Packets）由 DynamicTooltipsLib 作者记录，与本插件无关。
• RPGLeveling — 可选；仅在其存在时用于 Exp Boost 经验值。