HeartForge v1.3.1

HeartForge is a complete Lifesteal SMP plugin for Paper servers: players steal hearts on kill, withdraw hearts into tradeable items, get eliminated at zero hearts, and come back with a craftable Revive Crystal — with bounties, a stats GUI, a hearts leaderboard, epic kill effects, Discord webhook notifications and PlaceholderAPI support on top.

What makes HeartForge different from every other lifesteal plugin is that it is built anti-abuse-first. Most lifesteal servers die the same three deaths: someone finds an item dupe and prints hearts, someone farms hearts off their own alt accounts, or a hacked admin account wipes the economy overnight. HeartForge was designed from the first line of code to survive all three. Every heart change runs through one transactional engine and is flushed to disk instantly with atomic file writes — a crash, relog or inventory glitch cannot dupe a heart. Every heart item carries a unique server-minted token that can only ever be redeemed once, so even a successful item-duplication exploit is worthless. Alt-farming is blocked at the network level. And your admin commands stay locked behind a click-entered PIN even if your own account gets hacked.

If you are running (or launching) a Lifesteal SMP, a hearts-based PvP server, or a hardcore survival server with eliminations and revives, HeartForge gives you the full player-facing experience and the safety rails to keep its economy intact for months — not just a weekend.




⚔ Core Lifesteal Mechanics

Kill a player, take their heart. Your max-health bar grows, theirs shrinks — real max health, not a scoreboard trick. Everything about the exchange is configurable.

• Steal hearts on kill — killer gains hearts, victim loses hearts (default 1 and 1, each independently configurable — including 0, so you can run asymmetric economies like “kills count for bounties and stats, but no hearts move”).
• Real max-health bar — 1 heart = 1 full vanilla heart (2 HP) on the actual health bar. Attribute resolution is version-robust across the 1.20/1.21 attribute rename, so one jar works on both.
• Configurable limits — starting hearts (default 10), maximum (default 20), minimum/elimination floor, all changeable live in-game with /hf setmax, /hf setmin, /hf setstarting — no config editing, no restart.
• Optional natural-death loss — make falls, lava and mobs cost hearts too, or keep the default “you only lose hearts to other players.”
• Heart-cap behavior you choose — when a killer is already at max hearts, either the victim’s heart is still burned (default) or nothing is taken.
• Epic kill effects — the moment a heart is actually stolen: a cosmetic lightning strike on the victim (no damage, no fire), a burst of 40 heart particles, a level-up sound for the killer, and a big on-screen “❤ You took their heart” title. Every effect individually toggleable; particle and sound fully configurable (custom resource-pack sounds work too).
• Disabled worlds — protect your lobby, creative or event worlds from heart loss entirely.

Withdraw & Redeem — a Real Heart Economy

Turn hearts into physical, tradeable items and build a player-driven heart market. /withdraw [amount] converts your hearts into glowing heart items (default: an enchant-glint Nether Star — material, name, lore and glow are all configurable). Redeem them back three ways: right-click the item, /redeem for the item in hand, or /redeem all for your whole inventory at once. Heart items survive trades, chests, hoppers and restarts — their identity lives in persistent item data, not in the display name, so they can’t be faked with an anvil.

• You can never withdraw yourself into elimination — the plugin enforces a survival floor no matter how the config is set.
• Withdraw caps — limit how many hearts one command can convert (default 10).
• Crash-safe by design — hearts are removed and saved before items are created, and redeemed tokens are saved before hearts are credited. A server crash at the worst possible moment can never create value out of thin air.
• Inventory-safe — a withdraw is refused cleanly when you don't have room for the items; a full inventory can never destroy hearts.

Eliminations & Revives

Hit the heart floor and you’re out. You pick what “out” means:

• SPECTATOR (default) — the player is locked into spectator mode until revived. No data is wiped.
• BAN — a real server ban, temporary (auto-revive with 5 hearts when it expires) or permanent. The auto-revive is tamper-proof: it keys off the stored expiry timestamp, so an external /pardon can’t hand out a free revive.
• KICK — kicked and blocked from rejoining until revived.

Eliminations can be broadcast server-wide and posted to Discord. Carried heart items are voided on elimination (configurable), closing the classic “withdraw your hearts before dying, redeem after revive” loophole. Staff revive for free with /revive <player> — which works even while the target is offline and lifts their ban automatically.


The Craftable Revive Crystal

The comeback item your players will grind for. By default it’s crafted from 4 diamond blocks + 4 nether stars + 1 enchanted golden apple in a fully configurable shaped recipe (or disable the recipe and sell crystals in crates instead). A player holding a crystal runs /revive <player> and spends it to bring a fallen friend back at 5 hearts — no staff needed, which means your eliminations stay dramatic without generating support tickets. The crystal is identified by hidden persistent data, so a renamed Totem of Undying can’t counterfeit it, and it’s only consumed after the plugin confirms the target is actually eliminated.


Heart Bounties

/bounty <player> <hearts> stakes your own hearts on a rival’s head — no money economy or Vault required. Pots stack: multiple players can pile onto the same head, and whoever lands the killing blow claims the pot in a single kill, with a server-wide broadcast (and an optional gold Discord embed). Payouts flow through the same audited heart engine as everything else, so they always respect the server heart cap. /bounty list shows the top bounties on the server. Bounties persist across restarts and stay on a head until legitimately claimed.

And because bounty payouts sit behind the anti-alt checks: you cannot place a bounty on yourself and collect it with an alt. A same-network or cooldown-blocked kill pays zero bounty. Self-bounties are blocked outright, and you can never stake yourself below the elimination floor.


Stats GUI & Leaderboards

/stats [player] opens a clean 3-row menu: the player’s actual skin-textured head, hearts (current/max), kills, deaths, a live K/D ratio, playtime (shown live for online players), current bounty on their head, and Alive/Eliminated status. Every click is cancelled — it’s pure display, nothing can be dragged out.

Players own their privacy: /stats set private hides your stats from other players (staff with a bypass permission can still see them). /hearts top prints the server heart leaderboard — it ranks offline players too and always shows fresh counts for online ones.

🛡 The Anti-Abuse Layer — Your Economy’s Moat

This is the reason HeartForge exists. Hearts are your server’s currency; HeartForge treats them like one.

• Dupe-proof heart items — every heart item carries a unique, server-minted token in persistent item data, tracked in a ledger on disk. A token redeems exactly once: if a player duplicates the item with any exploit, the first redeem consumes the token and every copy is detected and voided with zero hearts paid.
• Atomic, crash-proof storage — every heart change is written immediately using write-to-temp + atomic rename. A crash mid-write can’t corrupt or half-apply a heart count. The server-side count — never the item — is the source of truth.
• Anti-alt-farming (on by default) — kills between accounts on the same IP transfer no hearts, and after stealing from a victim you can’t gain from that same victim again for a cooldown (default 1 hour). With household grouping enabled, the cooldown covers every account on the victim’s connection — rotating alts doesn’t work. The kill still counts for stats; the heart simply doesn’t move.
• Combat tagging — PvP damage tags both fighters for 15 seconds with a live action-bar countdown (“⚔ In combat: 12s”). Logging out while tagged kills you, charges the heart to your attacker’s credit, and announces it to the whole server. Commands (with a whitelist so /msg still works) and elytra escapes are blocked while tagged.
• Totem block in PvP — a Totem of Undying can’t save a combat-tagged player and cheat the heart loss. Outside of combat, totems behave normally.
• New-player grace period — optionally make fresh joins unkillable-for-hearts for their first minutes, so new players aren’t spawn-camped straight into elimination and quit.
• Bypass permissions for staff testing — granular nodes to exempt staff from the alt checks or combat restrictions when you need to test.

Owner Security — Survives a Hacked Admin Account

Unique to HeartForge: admin commands are protected by an owner PIN, entered on a click-based PIN pad GUI — the normal flow keeps your PIN out of chat logs, command history and your stream, because you click it instead of typing it. (A typed fallback exists purely as an emergency escape hatch in case the GUI ever fails to open.)

• Even an OP can’t touch your economy — heart-changing admin commands require /hf auth first. Sessions expire (default 15 min) and are wiped on logout, so the PIN is required every single login.
• Login wall — an unauthenticated admin who joins is frozen completely: blinded, locked in place, chat and commands cancelled, with a full-screen “ LOCKED” title and the PIN pad auto-opened. A hacker on your account sees a keypad and nothing else. While locked, tab-completion hides all sensitive subcommands and every argument hint.
• Two-step confirmations — server-changing commands (setmax, setmin, setstarting, reload) additionally ask “Are you sure?” and require /hf confirm within 30 seconds.
• Stored the right way — the PIN is saved only as a salted SHA-256 hash in its own file. Never plaintext, never in config.yml.
• You can never lock yourself out — the server console is always trusted; deleting one file from console resets the PIN.

Server-Owner Tools & Integrations

• Full audit trail — every heart change ever made is appended to audit.log with timestamp, reason (KILL_GAIN, WITHDRAW, ADMIN_SET, BOUNTY_CLAIM…), actor, and before → after counts. When a player claims they “lost hearts to a bug,” you’ll know in ten seconds.
• Discord webhooks, zero extra plugins — paste one webhook URL and get clean colored embeds for kills, eliminations, revives and bounties (withdraw/redeem embeds available but off by default). Fully async — Discord latency never touches your main thread — and posts can never ping Everyone.
• PlaceholderAPI (optional soft-hook) — 7 placeholders for scoreboards and tab: %heartforge_hearts%, %heartforge_max%, %heartforge_min%, %heartforge_eliminated%, %heartforge_rank%, %heartforge_top_<N>_name%, %heartforge_top_<N>_hearts% — leaderboard values are cached for 30 seconds so tick-rate scoreboards never hammer your disk.
• Every message customizable — 75+ message keys in messages.yml, all MiniMessage (gradients, hex colors), with a branded gradient prefix. Most messages can be silently disabled by setting them to an empty string. Update-safe: message keys added by new versions fall back to built-in defaults automatically, so upgrading never breaks your messages and never overwrites your edits.
• Self-healing config validation — contradictory values (a minimum above the maximum, an unknown material or elimination mode) are auto-corrected to safe values on load, with console warnings telling you what was fixed. A typo can’t break your heart math.
• In-game live admin — /hf sethearts, /hf givehearts (work on offline players too), /hf info (hearts, elimination state, live anti-dupe token count, security status), /hf reload hot-reloads config, messages and the crystal recipe.

⌨ Commands


Also: heartforge.bypass.altcheck (default false) and heartforge.bypass.combat (op) for staff testing.

⚙ Configuration at a Glance

Clean, fully commented config — most sections have more options than shown:


FAQ

Does it work on 1.21? Yes — one jar runs on Minecraft 1.20.x through 1.21.x (built against the 1.20.4 API on purpose, with version-robust handling of the 1.21 attribute and enchantment renames; tested live on Paper 1.21.11).

What server software do I need? Paper or a Paper fork (Purpur, Pufferfish) and Java 21+. No Vault, no MySQL, no dependencies — PlaceholderAPI is an optional soft-hook.

Can hearts be duped with an item-duplication exploit? No. Every heart item has a one-time-use token in a server-side ledger. The dupe copy fails validation, is voided, and pays nothing.

Can players farm hearts off their own alt accounts? Not with default settings: same-IP kills transfer nothing, repeat kills on the same victim (or the same household of accounts) are cooldown-limited, and bounties are only paid on kills that pass those checks.

Can players revive friends without staff? Yes — the craftable Revive Crystal. Staff can also /revive for free, even while the target is offline.

Can I change how many hearts are stolen per kill? Yes — killer gain and victim loss are independent (0 is valid for either), natural deaths can optionally cost hearts, and all limits are adjustable live in-game.

Is the jar obfuscated? No — you get a standard, unobfuscated jar. What you download is exactly what runs on your server, and the exact shipped jar is verified by a full integration test suite on a live server before every release.

Are messages translatable? Fully — 75+ MiniMessage keys with hex/gradient support; most messages can be individually disabled; updates never overwrite your edits.

Compatibility & Requirements

• Server: Paper / Purpur / Pufferfish — Minecraft 1.20.x – 1.21.x (tested live on 1.21.11)
• Java: 21 or newer
• Dependencies: none required · PlaceholderAPI optional
• Storage: flat files with atomic writes — no database setup

Support & Updates
Join the official HeartForge Discord — support, update news and feature requests:
► discord.gg/SEhqKGZuR
Actively maintained with day-one compatibility updates for new Minecraft versions. Bug reports get answered, not ignored. Every release is regression-tested with an automated suite of 40+ end-to-end checks on a live Paper server before upload.

HeartForge is original software implementing the generic “lifesteal” game mechanic. It is not affiliated with, derived from, or endorsed by any branded server or other plugin.