HyToolVariants adds randomized tool stat variants so every crafted or looted pickaxe/hatchet/shovel/hoe/shears can roll different mining or utility bonuses. Variants are stored per item and persist through trading, storage, and server restarts.

In construction

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

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

✅ Key features

Unique rolls per tool — the same pickaxe can be stronger or weaker depending on its variant.
Persistent per-item data — variants are stored on the ItemStack (BSON metadata).
Tools-only behavior — variants apply to pickaxes, hatchets, shovels, hoes, and shears (where a variant is category-tagged).
Ore-only Vein Mining — VeinMining breaks connected ore blocks only (tier controls max blocks).
Night Vision — tools that roll Night Vision brighten the scene while held via PostFx and optional dynamic light (tunable in config). Default threshold is 0.0 so typical rolls (often 0.80–1.20) always qualify; set nightVisionLightRadius: -1 for torch-style maximum radius if desired.
In-game config menu — open with /htv or /htv menu. Toggle enabled, debug logs, performance mode, drop modifiers, blacklists, and more; change language; save or reload config without editing files. UI and status messages are translated for supported languages.
Debug log creation — when debug is enabled, a timestamped log file is created under mods/HyToolVariants/Logs/ for troubleshooting (logging is asynchronous).
Variant rating in tooltips — when DynamicTooltipsLib (e.g. 1.5.x) is present, tooltips show a 5-star rating and percent first. The dependency is optional; without it, the mod still runs.
XP integration — ExpBoost can integrate with RPGLeveling to award XP per block break (if available).

✨ Tool variants (highlights)

Pickaxes:

Reach — longer block interaction reach while holding the tool (if supported by engine stat path).
Mining Speed — mining performance multiplier (metadata / stat sync where available).
Branch Mine — breaks extra blocks in a short line from the broken block.
Strip Mine — line-breaking along the look direction.
Vein Mining — connected ore-only flood-fill (configurable globs per tier).
Ore Yield — Fortune-style extra ore drop scaling.
Ore Sense — prospecting-style feedback when breaking blocks (pickaxes).
Auto Smelt — chance to smelt raw ore drops into ingots.

Hatchets:

Tree Feller — breaks connected logs matching configured log ID globs.
Lumberjack — extra wood/log drops from logs.

Shovels:

Branch Dig — breaks a 3×3 face of diggable blocks (per config).

Hoes:

Gardener — extra crop/plant drops from crop blocks.
Branch Tiller — tills a wider area of soil (per config).

All tools (where rolled):

Durability / Unbreaking / Efficiency / Movement Speed / Night Vision / Exp Boost — utility and passive effects; Night Vision uses client PostFx + optional dynamic light (see config keys nightVision*).

Shears:

Shear Speed — faster shearing when this variant rolls (shears-only category).

📊 Default variant pool & rolls (variantPool)

Each eligible tool rolls variantCount stats from the pool (default 0–3 per item). Weights and multiplier ranges are in config.json5.
category strips stats that do not match the tool (e.g. pickaxe-only stats never roll on a hoe).

Stat ID	UI label	Category
`Reach`	Block Reach	(any tool)
`BranchMine`	Branch Mine	PICKAXE_ONLY
`MiningSpeed`	Mining Speed	PICKAXE_ONLY
`StripMine`	Strip Mine	PICKAXE_ONLY
`OreYield`	Fortune	PICKAXE_ONLY
`OreSense`	Ore Sense	PICKAXE_ONLY
`AutoSmelt`	Auto Smelt Chance	PICKAXE_ONLY
`TreeFeller`	Tree Feller	HATCHET_ONLY
`Lumberjack`	Lumberjack	HATCHET_ONLY
`BranchDig`	Branch Dig	SHOVEL_ONLY
`Gardener`	Gardener	HOE_ONLY
`BranchTiller`	Branch Tiller	HOE_ONLY
`ShearSpeed`	Shear Speed	SHEARS_ONLY
`DurabilityBonus`	Durability	(any tool)
`Unbreaking`	Unbreaking	(any tool)
`Efficiency`	Efficiency	(any tool)
`MovementSpeed`	Move Speed	(any tool)
`NightVision`	Night Vision	(any tool)
`ExpBoost`	Exp Boost	(any tool)

Tool special effects (separate from multId; see toolSpecialEffects in config):

Effect ID	Label	Default notes
`VeinMining`	Vein Mining	Pickaxes (`Pickaxe` glob); ore-only chain break; tiers / max blocks / ore globs configurable

⚙️ Configuration & files (server owners)

Paths are relative to the server working directory (folder that contains mods/).

Path	Purpose
`mods/HyToolVariants/config.json5`	Main config — JSON5 (comments, trailing commas). Created from JAR defaults if missing. Edit by hand or via /htv UI (needs permission). `/htv reload` reloads from disk without restart.
`mods/HyToolVariants/Languages/{code}.json5`	UI / tooltip strings per language. Set `language: "xx"` in main config or in the menu. Bundled languages are extracted from the JAR when a file is missing.
`mods/HyToolVariants/Logs/debug_YYYY-MM-DD_HH-mm-ss.log`	Debug log — created when `debug: true` (async; one file per server start; not auto-deleted).

Shipped inside the JAR / asset pack (do not edit unless you repack): default HyToolVariants/config.json5 (and fallback HyToolVariants/config/HyToolVariants.json5); UI layout Common/UI/Custom/HyToolVariants/HwvConfig.ui. Plugin declares IncludesAssetPack: true.

Legacy migration — if the paths above are missing, the mod may copy from: mods/HyToolVariants_HyToolVariants/config.json5, plugin-data config/HyToolVariants.json5, HyToolVariants/config.json5 under data dir, or mods/HyToolVariants/config/HyToolVariants.json5.

Item metadata — variant BSON is stored under the key metaRoot (default hyweaponvariants for compatibility).

Night Vision keys — nightVisionBloomIntensity, nightVisionBloomPower, nightVisionThreshold (default 0.0), nightVisionLightRadius / RGB (0 = no dynamic light on player; -1 = max radius / torch-style). If Night Vision felt inactive on many tools, ensure nightVisionThreshold: 0.0.

🌐 Supported languages

Tooltips and UI strings can be translated. Set language: "xx" in config.json5 or change it in the /htv menu. Language files are in mods/HyToolVariants/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 (players only — not for console in this build)

Base: /htv — alias /hytoolvariants (identical).

Usage	Aliases	What it does
`/htv` (no args)	—	Opens the config UI (requires `help` then `menu` permissions — see below).
`/htv help`	`/htv ?`	Help text and version.
`/htv version`	`/htv ver`, `/htv v`	Mod version string.
`/htv reload`	—	Reload `mods/HyToolVariants/config.json5` from disk (no restart).
`/htv menu`	`/htv ui`	Open the config UI.
`/htv reroll`	`/htv rr`	Hold an eligible tool — remove current variant and roll a new one.
`/htv apply`	`/htv force`	Hold a tool — force-apply a variant if missing and eligible.
`/htv dump`	—	Hold an item — print variant metadata and debug lines to chat.
`/htv rolltest`	`/htv rt`	Staff / diagnostics: bulk simulation of random rolls (optional `[count]` `[itemId]`); does not create items. Default item id in code is a weapon example — set `itemId` to your pickaxe id for tool-focused checks.

🔐 Permissions (LuckPerms / any plugin that adds Player.hasPermission(String))

Permission strings use the legacy prefix hyweaponvariants.command.* (same family as older HyWeaponVariants packs — intentional for existing permission files).

Permission node	Allows
`hyweaponvariants.command.help`	`/htv` with no args (first check), `/htv help`, `/htv version`
`hyweaponvariants.command.menu`	Opening the config 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`	In-game UI buttons that save or change persisted config on disk

No permission plugin (no hasPermission on the player): everyone passes the light help gate. Commands that change config, open the menu, modify held items, or dump debug output require operator if isOp() exists; otherwise those actions are denied.

Example policy (LuckPerms or similar) — not enforced by the mod; for inspiration only:

Everyone: hyweaponvariants.command.help (read help/version).
Staff / builders: add hyweaponvariants.command.menu (open UI) and optionally .edit (save toggles).
Admins: add hyweaponvariants.command.reload, .reroll, .apply, .dump (and .edit if not already). Or grant hyweaponvariants.command.* to a single group.

Coexistence with other combat mods — in config.json5, disableCombatSystemsWhenHyArmourVariantsPresent and disableCombatSystemsWhenHyWeaponVariantsPresent (default true) let HyToolVariants yield weapon hit processing when those mods are installed; tool behaviour (block break, durability, passives) stays in HyToolVariants.

📦 Optional dependencies (manifest)

DynamicTooltipsLib (org.herolias:DynamicTooltipsLib) — optional; richer tooltips. Without it the mod runs; tooltips are simpler.
HyWeaponVariants — optional; when present you can yield hit processing to that mod via config so both mods coexist.

Other integrations (e.g. RPGLeveling for Exp Boost, HyArmourVariants) are detected at runtime — not hard dependencies.

🛡️ Technical notes

Built with update resilience in mind: safe reflection and fallbacks, metadata versioning, stable fingerprinting. Tool variants are stored by stat id 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 HyToolVariants jar from your mods folder.
Clear mod data — delete the folder mods/HyToolVariants (config and language files).
Restart — restart the game/server.
Reinstall — put the HyToolVariants jar back and start again.

If it still does not appear, check the server/client log for errors mentioning HyToolVariants. The mod falls back to defaults if config or language files are missing.

📝 Notes

Drops and XP can vary due to vanilla RNG and config multipliers — compare averages over multiple vein breaks.
Changelog — Curseforge_Changelog.md lists version history, variant tables, commands, permissions, and config file layout; the ## [version] heading matches version in gradle.properties (e.g. 0.0.1BETA).

📜 Compatibility

DynamicTooltipsLib — optional; uses the public tooltip provider API. Other mods’ known issues (e.g. Soft Packets) are documented by DynamicTooltipsLib’s author, not this plugin.
RPGLeveling — optional; used only for Exp Boost XP when present.