HyWeaponVariants

---

HyWeaponVariants adds randomized stat variants to weapons so every crafted or looted weapon can roll different performance. Variants are stored per item and persist through trading, storage, and server restarts.

---

---

Disclaimer: This mod is still in development! Please report bugs / feature requests on the CurseForge project page or Discord.

When reporting issues, include: mods/HyWeaponVariants/config.json5, your language file from mods/HyWeaponVariants/Languages/ (if you changed it), and the relevant server log snippet. Enable debug in config (or via the /hwv menu) to get detailed logs; a timestamped debug log file is written to mods/HyWeaponVariants/Logs/debug_YYYY-MM-DD_HH-mm-ss.log. Debug is off by default.

---

✅ Key features

• Unique rolls per weapon — the same sword or axe can be stronger or weaker depending on its variant.
• Persistent per-item data — variants are stored on the ItemStack (BSON metadata).
• Weapon support: Stat Modifier weapons and vanilla-style melee (absolute damage calculators); applied on craft, pickup, move, or when opening containers.
• In-game config menu — open with /hwv or /hwv menu. Toggle enabled, debug logs, performance mode, on-hit effects, blacklists, and more; change language; save or reload config without editing files. UI and status messages are translated for all supported languages.
• Debug log creation — when debug is enabled (in config or via the menu), a timestamped log file is created under mods/HyWeaponVariants/Logs/ for troubleshooting. Logging is asynchronous so the game thread is not blocked.
• Variant rating in tooltips — when DynamicTooltipsLib is present, tooltips show a 5-star rating and percent first, then special effects, on-hit chances, and stat bonuses. Optional; mod works without it.
• Special attacks — weapons can roll one of five special effects (see table below) with configurable tier and rarity-based backfire (low-rarity weapons can backfire onto the user).
• On-hit effects — Stun, Burn, Poison, Freeze, Bleed, Thorns, Life Steal apply when the chance succeeds. Negative rolls can backfire onto the player (configurable); if the effect already applied to the target, it does not also backfire.
• Effect duration — the Effect Duration variant increases how long your applied debuffs last. Optional deployable/AoE rolls (e.g. Healing Totem radius).
• Shields: on-bash and on-block — Shields with variants get separate on-bash (offensive hit when you bash) and on-block (counter when you block an attacker) triggers. Each variant can be bash-only, block-only, or both; tooltips show "On bash (enemy):" and "On block (attacker):" for the relevant effects. Configurable via shieldBashTriggerChance and shieldBlockTriggerChance.

---

⭐ Variant star rating

When DynamicTooltipsLib is enabled, the first line of a variant weapon's tooltip shows a 5-star rating and overall variant percent (e.g. [****-] 91%). Filled stars (*) are yellow, empty slots (-) are grey; the percent reflects how strong the roll is (e.g. 0–150% by default). This line appears above special effects and all other stats.

---

✨ Special effects

Weapons can roll one of the following special attacks (proc on hit, configurable chance). Each has a tier (1–3); higher rarity weapons tend to roll better tiers. Low-rarity weapons have a configurable chance that the effect backfires (applies to you instead of the enemy). Epic/Legendary/Mythic typically have no backfire.

Special effect	What it does
Blazing Ring	Creates a ring of fire around you, damaging nearby enemies.
Frost Nova	Frost burst that slows and damages enemies in an area.
Poison Cloud	Releases a toxic cloud that poisons enemies over time.
Thunder Strike	Calls down lightning to strike multiple enemies.
Thorns Aura	Applies Thorns to enemies you hit, damaging them over time.

---

⚔️ On-hit effects

Weapons can roll and apply the following effects on hit (visible on the target as icons/duration). Thorns can be set to buff the attacker instead of the target. Life Steal heals based on damage dealt (configurable multiplier and min heal); optional visual effect and toast. When damage comes from DoTs or deployables, the mod can use the last attacker to apply on-hit effects (configurable). Backfire: if a roll is negative (e.g. reduced Freeze), the effect can apply to the player at a chance — but only when it did not already apply to the target on that hit. Per-effect cooldown is configurable.

Effect	Variant stat	Description
Stun	Stun Chance	Chance to stun the target on hit.
Burn	Ignite Chance	Chance to set the target on fire.
Poison	Poison Chance	Chance to poison the target over time.
Freeze	Freeze Chance	Chance to freeze/slow the target.
Bleed	Bleed Chance	Chance to cause bleeding (DoT).
Thorns	Thorns	Chance to apply Thorns; can be set to buff the attacker instead of the target.
Life Steal	Life Steal	Heals you based on damage dealt; configurable multiplier, min heal, and visual effect.

---

📊 All variants

Weapons roll a subset of these stats (count and pool are configurable). Each variant has a multiplier range (e.g. 0.80–1.20); the roll determines how strong that stat is on the weapon.

Variant ID	Display name	Typical range	Description
BonusDamage	Bonus Damage	80–130%	Multiplies base weapon damage.
CriticalChance	Crit Chance	85–140%	Increases chance to land a critical hit (with base crit chance from config).
CriticalDamage	Crit Damage	80–150%	Multiplies damage when the hit is a critical.
ArmorPenetration	Armor Penetration	80–135%	Reduces target armor effectiveness.
ElementalDamage	Elemental Damage	75–145%	Scales elemental/fire/ice etc. damage.
PoisonChance	Poison Chance	70–150%	Chance to apply Poison on hit.
IgniteChance	Ignite Chance	70–150%	Chance to set the target on fire (Burn) on hit.
FreezeChance	Freeze Chance	70–145%	Chance to freeze or slow the target on hit.
StunChance	Stun Chance	65–140%	Chance to stun the target on hit.
BleedChance	Bleed Chance	70–150%	Chance to cause bleeding (DoT) on hit.
EffectDuration	Effect Duration	75–150%	Increases how long your applied debuffs last on the target.
LifeSteal	Life Steal	70–150%	Chance to heal based on damage dealt.
Thorns	Thorns	80–130%	Chance to apply Thorns (or buff yourself); configurable on-hit rule.
AttackSpeed	Attack Speed	85–120%	Attack/swing speed (if the game uses this entity stat).
MovementSpeed	Move Speed	90–115%	Movement speed while holding the weapon.
Knockback	Knockback	70–140%	How much you knock back the target.
Reach	Reach	85–125%	Melee or interaction range.
ProjectileSpeed	Projectile Speed	80–135%	Speed of projectiles (e.g. bows, thrown).
ChargeSpeed	Charge Speed	80–130%	Speed of charge/sprint attacks.
BounceChance	Pierce / Bounce	70–150%	Chance for projectiles to pierce or bounce.
Mana	Mana Cost	80–120%	Mana cost per use (lower % = cheaper).
SignatureEnergy	Signature Energy	80–120%	Signature/ability energy cost.
Stamina	Stamina Cost	80–115%	Stamina cost per attack or ability.
DurabilityBonus	Durability	75–150%	How much durability the weapon has (or how fast it degrades).
AoeRadius	AoE radius	75–150%	Radius of area effects (e.g. deployables).
HealingRadius	Healing radius	75–150%	Radius of healing effects (e.g. Healing Totem).
Vengeance	Vengeance	80–150%	Passive: more damage as your health decreases (scales with missing HP).
ShieldBreaker	Shield Breaker	85–130%	Bonus damage vs blocking targets; configurable backfire (e.g. Disarm).

---

🛠️ Compatibility & integration

• Salvager / Processing Bench — variant weapons work in the Salvager. Item IDs are normalized while the container is open so recipes accept them. When you take the weapon back (move it to your hotbar or inventory, or close the UI with the item still in your inventory), the same variant is restored — the weapon is not rerolled. Variant cache is only cleared when the weapon is fully salvaged (recipe completed).
• Builder's Workbench — weapons and items keep their variant when used in the Builder's Workbench; the mod detects the workbench window and does not reroll or strip variants when the workbench returns or recreates the item.
• Romnas Quality Crafting — when both mods are installed, quality item IDs (e.g. Weapon_Sword__RARE) are resolved to the base item for variants and Salvager (configurable; no extra dependency).
• Weapon Mastery (ludwici) — compatible; variant and mastery bonuses stack.
• Modded weapons supported when defined as weapons or under Items.Weapons (or custom category prefixes in config).

---

⚙️ Configuration

• Config path: mods/HyWeaponVariants/config.json5 (JSON5, created on first run). Legacy paths are migrated automatically.
• In-game config menu — run /hwv or /hwv menu (with permission hyweaponvariants.command.menu) to open the config UI. Toggle enabled, debug logs, performance mode, on-hit effects, blacklists, etc.; switch language; save or reload config without editing files. The UI is translated for all supported languages.
• Debug logs — when debug is enabled (in config or via the menu; off by default), a timestamped log file is created at mods/HyWeaponVariants/Logs/debug_YYYY-MM-DD_HH-mm-ss.log. Writes are asynchronous so the game thread is not blocked. One file per server start; old files are not deleted automatically.
• Min/max roll ranges, distribution (uniform / triangular / normal), variant count per weapon, which stats can roll, per-item or per-category overrides.
• When to apply variants: inventory change, pickup, container open; poller for held-weapon sync. Optional performance mode: higher poller intervals, disable last-attacker fallback, hide on-hit tooltip line.
• Tooltip options: show header (stars + %), multipliers, durability, on-hit effects. Rarity bias for rolls and special-attack backfire chances.
• Effect durations, on-hit cooldowns, Life Steal multiplier and visual. /hwv reload applies config changes without restarting the server.

---

🌐 Supported languages

Tooltips and UI strings can be translated. Set language: "xx" in config.json5 (e.g. language: "de" for German), or change it in the /hwv menu Language tab. Language files are in mods/HyWeaponVariants/Languages/ and are extracted from the mod on first run. You can add your own xx.json5 (same structure as en.json5) to support more languages.

Code	Language
en	English
de	German (Deutsch)
cs	Czech (čeština)
uk	Ukrainian (українська)
fr	French (français)
es	Spanish (español)
pl	Polish (polski)
ru	Russian (русский)
pt	Portuguese (português)
it	Italian (italiano)

---

📋 Commands

• /hwv — Open the in-game config menu (requires hyweaponvariants.command.menu; if you lack help permission, shows "no permission" instead).
• /hwv menu or /hwv ui — Open the in-game config menu.
• /hwv help or /hwv ? — Show version and command list.
• /hwv version (or ver / v) — Show mod version.
• /hwv reload — Reload config from disk (no server restart).
• /hwv reroll (or rr) — (hold a weapon) Strip its current variant and roll a brand-new one.
• /hwv apply (or force) — (hold a weapon) Force-apply a variant to the held item (if it doesn't have one).
• /hwv dump — (hold an item) Print variant metadata for debugging.

Alias: /hyweaponvariants

Permissions (compatible with LuckPerms and similar; uses hasPermission(String) when available):

• hyweaponvariants.command.help — /hwv help, /hwv version (and seeing help when you have no other permission).
• hyweaponvariants.command.menu — /hwv, /hwv menu, /hwv ui (open the in-game config UI).
• hyweaponvariants.command.reload — /hwv reload
• hyweaponvariants.command.reroll — /hwv reroll
• hyweaponvariants.command.apply — /hwv apply
• hyweaponvariants.command.dump — /hwv dump

Without a permission plugin: help and version are allowed for everyone; menu, reload, reroll, apply, and dump require op (when isOp() exists). Console can run all commands.

---

🛡️ Technical notes

Built with update resilience in mind: safe reflection and fallbacks, metadata versioning, stable fingerprinting. Variants are stored by stat id (v2+) so future stat reordering is less likely to break old items.

---

🔧 Plugin not showing / not loading after update

If the game does not see the mod after an update (or after rollback/reinstall), try:

1. Remove the mod — Delete the HyWeaponVariants JAR from your mods folder.
2. Clear the mod data — Delete the folder mods/HyWeaponVariants (config and language files) so the plugin starts clean.
3. Restart the game to clear in-memory state.
4. Reinstall — Put the HyWeaponVariants JAR back in the mods folder and start the game again.

If the plugin still does not appear, check the server/client log for errors mentioning HyWeaponVariants. The mod falls back to defaults if config or language files are missing, so it should at least load.

---

📝 Notes

• Damage can still vary due to vanilla RNG/crit — compare averages over many hits to see variant differences.
• Config and languages live under mods/HyWeaponVariants/ (see server log on first run for the exact path). Debug log files are in mods/HyWeaponVariants/Logs/ when debug is enabled.