Description
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
/hwvor/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
shieldBashTriggerChanceandshieldBlockTriggerChance.
⭐ 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
/hwvor/hwv menu(with permissionhyweaponvariants.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 (requireshyweaponvariants.command.menu; if you lack help permission, shows "no permission" instead)./hwv menuor/hwv ui— Open the in-game config menu./hwv helpor/hwv ?— Show version and command list./hwv version(orver/v) — Show mod version./hwv reload— Reload config from disk (no server restart)./hwv reroll(orrr) — (hold a weapon) Strip its current variant and roll a brand-new one./hwv apply(orforce) — (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 reloadhyweaponvariants.command.reroll—/hwv rerollhyweaponvariants.command.apply—/hwv applyhyweaponvariants.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:
- Remove the mod — Delete the HyWeaponVariants JAR from your
modsfolder. - Clear the mod data — Delete the folder
mods/HyWeaponVariants(config and language files) so the plugin starts clean. - Restart the game to clear in-memory state.
- 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 inmods/HyWeaponVariants/Logs/when debug is enabled.