HeartSystemKb

A simple, lightweight heart system for PvP servers, battle royales and events. Win a fight, earn an extra heart! Hearts either drop from the defeated player as an item or are granted to the killer instantly - you choose with one command.

---

🇺🇸 English Description

HeartSystemKb lets players grow their maximum health by killing other players, up to a cap of 20 hearts. Perfect for Battle Royale (KB) events, UHC-style games, lifesteal-like survival servers and any PvP mode where fights should matter.

✨ Features

• Two Reward Modes: Mode 1 drops a heart item from the victim, mode 2 adds the heart to the killer instantly. Switch any time with /heartsystem; your choice is saved in config.yml.
• Heart Item: The heart is a paper item with a custom name and lore. Right-click it to gain +1 max heart. It is tagged internally, so it can't be faked with a renamed paper.
• 20 Heart Cap: Max health is limited to 20 hearts (40 HP). Hearts are never used up if you are already at the cap.
• Withdraw a Heart: /heart take converts one of your hearts back into an item (minimum 10 hearts, once per server session) so players can trade or hide hearts.
• Extra Hearts Survive Death: Earned hearts stay after dying and respawning.
• Smart Right-Click: Right-clicking a chest, door, button or other usable block with a heart in hand opens the block and does not waste the heart.
• Top List & Admin Tools: /maxhealth shows the top 10 online players by health, /resetallhp resets everyone to 10 hearts.
• Optional Resource Pack Model: The heart uses PAPER with CustomModelData 10021, so you can give it your own texture.

🛠️ Commands & Permissions

• /heart take — Withdraws 1 heart into your inventory. (👤 Player Only)
• /heartsystem <1|2> — Switches the reward mode. Permission: heartsystem.admin (Ops by default) (👤 Player / 💻 Console)
• /maxhealth (aliases: /tophealth, /hptop) — Shows the top 10 online players by max health. (👤 Player / 💻 Console)
• /resetallhp — Resets the max health of all online players to 10 hearts. Permission: heartsystem.reset (Ops by default) (👤 Player / 💻 Console)

⚠️ Good to know

• Hearts are only rewarded for player kills (self-kills do nothing). The victim does not lose a heart.
• /heart take can be used once per player until the server restarts.
• /maxhealth only lists players who are currently online.
• Supported range: 1.21 - 26.2. Confirmed by testing on Purpur 1.21, 1.21.1, 1.21.3, 1.21.4, 1.21.5, 1.21.8, 1.21.11, 26.1.2 and 26.2; other versions in this range are expected to work but have not been tested individually.
• Tested on Purpur only. Paper, Spigot and Bukkit use the same Bukkit API but were not run separately.

---

🇷🇺 Описание на Русском

HeartSystemKb — лёгкая система сердец для PvP-серверов, королевских битв и ивентов. Выиграл бой — получил дополнительное сердце! Сердце либо выпадает предметом из убитого игрока, либо сразу добавляется убийце. Режим переключается одной командой.

✨ Особенности

• Два режима награды: режим 1 — из жертвы выпадает предмет-сердце, режим 2 — сердце начисляется убийце сразу. Переключается командой /heartsystem, выбор сохраняется в config.yml.
• Предмет-сердце: бумага со своим названием и описанием. ПКМ — +1 максимальное сердце. Предмет помечен внутри плагина, подделать переименованной бумагой нельзя.
• Лимит 20 сердец: максимум 20 сердец (40 HP). Если лимит достигнут, сердце не тратится.
• Снять сердце: /heart take превращает одно ваше сердце обратно в предмет (минимум 10 сердец, один раз за сессию сервера).
• Сердца сохраняются после смерти.
• Умный ПКМ: клик по сундуку, двери, кнопке и т. п. с сердцем в руке открывает блок и не тратит сердце.
• Топ и админ-инструменты: /maxhealth — топ-10 онлайн-игроков по здоровью, /resetallhp — сброс всех до 10 сердец.
• Модель для ресурс-пака: сердце — это PAPER с CustomModelData 10021, можно задать свою текстуру.

🛠️ Команды и Права

• /heart take — снимает 1 сердце в инвентарь. (👤 Только игрок)
• /heartsystem <1|2> — переключает режим награды. Право: heartsystem.admin (у операторов по умолчанию) (👤 Игрок / 💻 Консоль)
• /maxhealth (алиасы: /tophealth, /hptop) — топ-10 онлайн-игроков по здоровью. (👤 Игрок / 💻 Консоль)
• /resetallhp — сбрасывает здоровье всех онлайн-игроков до 10 сердец. Право: heartsystem.reset (у операторов по умолчанию) (👤 Игрок / 💻 Консоль)

⚠️ Стоит знать

• Сердца даются только за убийство игроков (самоубийство не считается). Жертва сердце не теряет.
• /heart take можно использовать один раз на игрока до перезапуска сервера.
• /maxhealth показывает только игроков, которые сейчас онлайн.
• Поддерживаемый диапазон: 1.21 - 26.2. Проверено тестами на Purpur 1.21, 1.21.1, 1.21.3, 1.21.4, 1.21.5, 1.21.8, 1.21.11, 26.1.2 and 26.2; остальные версии диапазона должны работать, но отдельно не проверялись.
• Тестировалось только на Purpur. Paper, Spigot и Bukkit используют тот же Bukkit API, но отдельно не запускались.

---

🚀 Installation / Установка

1. Download the HeartSystemKb-1.1.0.jar file.
2. Drop it into your server's plugins/ folder.
3. Restart your server.

---

📞 Contacts & Support / Контакты

Developed with ❤️ by egorkawww.

• Discord: egorkawww
• Telegram: @egorkawww

Copyright (c) 2026 egorkawww