HyWeaponVariants

---

HyWeaponVariants 为武器添加了随机属性变体，使每件制造或战利品武器都可能拥有不同的性能。变体信息会储存在每个物品上，并在交易、存储和服务器重启后持续存在。

---

---

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

报告问题时，请包含： mods/HyWeaponVariants/config.json5，来自 mods/HyWeaponVariants/Languages/ 的语言文件（如果你更改过），以及相关的服务器日志片段。在配置中（或通过 /hwv menu）启用 debug 以获取详细日志；带时间戳的调试日志文件将写入 mods/HyWeaponVariants/Logs/debug_YYYY-MM-DD_HH-mm-ss.log。调试模式默认关闭。

---

✅ 主要特性

• 每把武器的独特随机属性 — 同一把剑或斧头，根据其变体，可能更强或更弱。
• 持久的物品数据 — 变体信息储存在物品堆（BSON 元数据）上。
• 武器支持： 属性修改器武器和原版风格近战（绝对伤害计算器）；在制造、拾取、移动或打开容器时应用。
• 游戏内配置菜单 — 使用 /hwv 或 /hwv menu 打开。切换启用、调试日志、性能模式、命中效果、黑名单等；更改语言；无需编辑文件即可保存或重新加载配置。用户界面和状态消息已翻译成所有支持的语言。
• 创建调试日志 — 启用调试时（在配置中或通过菜单），会在 mods/HyWeaponVariants/Logs/ 下创建一个带时间戳的日志文件，用于故障排除。日志记录是异步的，因此不会阻塞游戏线程。
• 物品提示中的变体评级 — 当安装了 DynamicTooltipsLib 时，物品提示会首先显示 5星评级 和 百分比，然后是特殊效果、命中几率和属性加成。可选；模组不带它也能工作。
• 特殊攻击 — 武器可以随机获得五种特殊效果之一（见下表），具有可配置的等级和基于稀有度的反噬效果（低稀有度武器可能对使用者产生反噬）。
• 命中效果 — 眩晕、燃烧、中毒、冰冻、流血、荆棘、生命偷取在几率成功时生效。负面随机效果可能反噬玩家（可配置）；如果该效果已应用于目标，则不会同时产生反噬。
• 效果持续时间 — 效果持续时间变体增加你施加的减益效果的持续时间。可选的范围/可部署物品随机效果（例如治疗图腾半径）。
• 盾牌：盾击和格挡时 — 带有变体的盾牌会获得独立的 盾击时（你盾击时的攻击命中）和 格挡时（你格挡攻击者时的反击）触发条件。每个变体可以是仅盾击、仅格挡或两者兼有；提示文字会针对相关效果显示"盾击时（敌人）："和"格挡时（攻击者）："。可通过 shieldBashTriggerChance 和 shieldBlockTriggerChance 配置。

---

⭐ 变体星评级

当启用了 DynamicTooltipsLib 时，变体武器提示文字的 第一行 会显示 5星评级 和 总体变体百分比（例如 [****-] 91%）。实心星 (*) 为黄色，空位 (-) 为灰色；百分比反映了变体的强度（例如默认 0-150%）。此行显示在所有特殊效果和其他属性之上。

---

✨ 特殊效果

武器可以随机获得以下 特殊攻击 之一（命中时触发，几率可配置）。每个都有 等级（1-3）；稀有度更高的武器倾向于获得更好的等级。低稀有度武器有一定几率（可配置）使效果 反噬（施加给使用者而不是敌人）。史诗/传说/神话品质通常没有反噬。

特殊效果	效果说明
火焰之环	在你周围创造一道火环，伤害附近的敌人。
冰霜新星	霜冻爆发，在区域内减缓并伤害敌人。
毒云	释放一团有毒烟雾，随时间对敌人造成中毒效果。
雷霆打击	召唤闪电打击多个敌人。
荆棘光环	对你击中的敌人施加荆棘效果，随时间造成伤害。

---

⚔️ 命中效果

武器在命中时可以随机获得并施加以下效果（在目标上以图标/持续时间显示）。荆棘 可以设置为增强攻击者而非目标。生命偷取 根据造成的伤害进行治疗（可配置倍率和最小治疗量）；可选的视觉效果和提示。当伤害来自持续伤害或可部署物品时，模组可以使用 最后攻击者 来施加命中效果（可配置）。反噬：如果随机结果为负（例如降低的冰冻效果），该效果有一定几率施加给玩家——但仅在该次命中效果未施加给目标时生效。每个效果的冷却时间可配置。

效果	变体属性	描述
眩晕	眩晕几率	命中时眩晕目标的几率。
燃烧	点燃几率	命中时点燃目标的几率。
中毒	中毒几率	随时间对目标造成中毒的几率。
冰冻	冰冻几率	冻结/减速目标的几率。
流血	流血几率	造成流血（持续伤害）的几率。
荆棘	荆棘	施加荆棘的几率；可设置为增强攻击者而非目标。
生命偷取	生命偷取	根据造成的伤害治疗你；可配置倍率、最小治疗量和视觉效果。

---

📊 所有变体

武器会从这些属性中随机获得一个子集（数量和池可配置）。每个变体都有一个倍率范围（例如 0.80-1.20）；随机值决定了该属性在武器上的强度。

变体 ID	显示名称	典型范围	描述
BonusDamage	额外伤害	80-130%	乘以基础武器伤害。
CriticalChance	暴击几率	85-140%	增加暴击几率（基于配置中的基础暴击率）。
CriticalDamage	暴击伤害	80-150%	当命中为暴击时，乘以伤害。
ArmorPenetration	护甲穿透	80-135%	降低目标护甲效果。
ElementalDamage	元素伤害	75-145%	缩放元素/火焰/冰霜等伤害。
PoisonChance	中毒几率	70-150%	命中时施加中毒的几率。
IgniteChance	点燃几率	70-150%	命中时点燃目标（燃烧）的几率。
FreezeChance	冰冻几率	70-145%	命中时冻结或减速目标的几率。
StunChance	眩晕几率	65-140%	命中时眩晕目标的几率。
BleedChance	流血几率	70-150%	命中时造成流血（持续伤害）的几率。
EffectDuration	效果持续时间	75-150%	增加你施加给目标的减益效果的持续时间。
LifeSteal	生命偷取	70-150%	根据造成的伤害，有一定几率进行治疗。
Thorns	荆棘	80-130%	施加荆棘（或增强自身）的几率；可配置命中规则。
AttackSpeed	攻击速度	85-120%	攻击/挥动速度（如果游戏使用此实体属性）。
MovementSpeed	移动速度	90-115%	手持武器时的移动速度。
Knockback	击退	70-140%	你击退目标的程度。
Reach	攻击距离	85-125%	近战或交互范围。
ProjectileSpeed	弹射物速度	80-135%	弹射物的速度（例如弓、投掷物）。
ChargeSpeed	蓄力速度	80-130%	蓄力/冲刺攻击的速度。
BounceChance	穿透/弹跳	70-150%	弹射物穿透或弹跳的几率。
Mana	法力消耗	80-120%	每次使用的法力消耗（较低百分比 = 更节省）。
SignatureEnergy	终结技能量	80-120%	终结技/技能能量消耗。
Stamina	体力消耗	80-115%	每次攻击或技能的体力消耗。
DurabilityBonus	耐久度	75-150%	武器拥有的耐久度（或它消耗多快）。
AoeRadius	范围效果半径	75-150%	区域效果的半径（例如可部署物品）。
HealingRadius	治疗半径	75-150%	治疗效果的半径（例如治疗图腾）。
Vengeance	复仇	80-150%	被动：生命值越低，造成更多伤害（根据损失的生命值缩放）。
ShieldBreaker	破盾者	85-130%	对格挡目标造成额外伤害；可配置反噬（例如缴械）。

---

🛠️ 兼容性与集成

• 回收器 / 处理台 — 变体武器可在回收器中使用。当容器打开时，物品 ID 会被标准化，以便配方可以接受它们。当你取回武器（将其移动到快捷栏或物品栏，或在物品仍在物品栏中时关闭界面）时，相同的变体会被恢复 — 武器不会被重新随机。仅在武器被完全回收（配方完成）时，变体缓存才会被清除。
• 建造者工作台 — 武器和物品在建造者工作台中使用时保持其变体；模组会检测工作台窗口，当工作台返回或重新创建物品时，不会重新随机或剥离变体。
• Romnas Quality Crafting — 当两个模组都安装时，品质物品 ID（例如 Weapon_Sword__RARE）会被解析为用于变体和回收器的基础物品（可配置；无额外依赖）。
• Weapon Mastery（ludwici） — 兼容；变体和精通加成可叠加。
• 当模组化武器被定义为武器或在 Items.Weapons 下（或配置中的自定义类别前缀）时受支持。

---

⚙️ 配置

• 配置路径: mods/HyWeaponVariants/config.json5 (JSON5，首次运行时创建)。旧路径会自动迁移。
• 游戏内配置菜单 — 运行 /hwv 或 /hwv menu（需要权限 hyweaponvariants.command.menu）以打开配置界面。切换启用、调试日志、性能模式、命中效果、黑名单等；切换语言；无需编辑文件即可保存或重新加载配置。界面已翻译成所有支持的语言。
• 调试日志 — 启用调试时（在配置中或通过菜单；默认关闭），会在 mods/HyWeaponVariants/Logs/debug_YYYY-MM-DD_HH-mm-ss.log 创建一个带时间戳的日志文件。写入是异步的，因此不会阻塞游戏线程。每次服务器启动生成一个文件；旧文件不会自动删除。
• 最小/最大随机范围，分布（均匀 / 三角形 / 正态），每把武器的变体数量，哪些属性可以随机，每物品或每类别覆盖。
• 应用变体的时机：物品栏变更、拾取、容器打开；用于手持武器同步的轮询器。可选的 性能模式：更高的轮询间隔，禁用最后攻击者回退，隐藏命中效果提示行。
• 提示文字选项：显示标题（星级 + %），倍率，耐久度，命中效果。随机数的稀有度偏差和特殊攻击反噬几率。
• 效果持续时间，命中效果冷却，生命偷取倍率和视觉效果。 /hwv reload 可在不重启服务器的情况下应用配置更改。

---

🌐 支持的语言

提示文字和界面字符串可被翻译。在 config.json5 中设置 language: "xx"（例如 language: "de" 对应德语），或者在 /hwv menu 的语言标签页中更改。语言文件位于 mods/HyWeaponVariants/Languages/，首次运行时从模组解压。你可以添加自己的 xx.json5（结构与 en.json5 相同）以支持更多语言。

代码	语言
en	英语
de	德语
cs	捷克语
uk	乌克兰语
fr	法语
es	西班牙语
pl	波兰语
ru	俄语
pt	葡萄牙语
it	意大利语

---

📋 命令

• /hwv — 打开游戏内配置菜单（需要 hyweaponvariants.command.menu；如果你没有帮助权限，则显示"没有权限"）。
• /hwv menu 或 /hwv ui — 打开游戏内配置菜单。
• /hwv help 或 /hwv ? — 显示版本和命令列表。
• /hwv version（或 ver / v） — 显示模组版本。
• /hwv reload — 从磁盘重新加载配置（无需重启服务器）。
• /hwv reroll（或 rr） — （手持武器） 移除其当前变体并随机一个全新的。
• /hwv apply（或 force） — （手持武器） 强制为手持物品应用一个变体（如果它还没有）。
• /hwv dump — （手持物品） 打印用于调试的变体元数据。

别名: /hyweaponvariants

权限（兼容 LuckPerms 等；在可用时使用 hasPermission(String)）:

• hyweaponvariants.command.help — /hwv help, /hwv version（以及在你没有其他权限时看到帮助信息）。
• hyweaponvariants.command.menu — /hwv, /hwv menu, /hwv ui（打开游戏内配置界面）。
• hyweaponvariants.command.reload — /hwv reload
• hyweaponvariants.command.reroll — /hwv reroll
• hyweaponvariants.command.apply — /hwv apply
• hyweaponvariants.command.dump — /hwv dump

无权限插件时：帮助和版本命令对所有人开放；菜单、重新加载、重新随机、应用和转储命令需要 op（当 isOp() 可用时）。控制台可以运行所有命令。

---

🛡️ 技术说明

构建时考虑了更新弹性：安全的反射和回退，元数据版本控制，稳定的指纹识别。变体按属性 id (v2+) 存储，因此未来的属性重新排序不太可能破坏旧物品。

---

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

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

1. 移除模组 — 从你的 mods 文件夹中删除 HyWeaponVariants JAR 文件。
2. 清除模组数据 — 删除文件夹 mods/HyWeaponVariants（配置和语言文件），以便插件从头开始。
3. 重启游戏 以清除内存中的状态。
4. 重新安装 — 将 HyWeaponVariants JAR 文件放回 mods 文件夹并再次启动游戏。

如果插件仍然不显示，检查服务器/客户端日志中是否有提及 HyWeaponVariants 的错误。如果配置或语言文件丢失，模组会回退到默认值，因此它至少应该加载。

---

📝 备注

• 由于原版随机数/暴击，伤害仍可能有所不同 — 比较多次攻击的平均值以查看变体差异。
• 配置和语言文件位于 mods/HyWeaponVariants/ 下（首次运行时查看服务器日志以获取确切路径）。启用调试时，调试日志文件位于 mods/HyWeaponVariants/Logs/ 中。