Description
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.
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: -1for torch-style maximum radius if desired. - In-game config menu — open with
/htvor/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 —
ExpBoostcan 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
variantCountstats from the pool (default 0–3 per item). Weights and multiplier ranges are inconfig.json5. categorystrips 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.editif not already). Or granthyweaponvariants.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
modsfolder. - 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.mdlists version history, variant tables, commands, permissions, and config file layout; the## [version]heading matchesversioningradle.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.