Skip to content

Home

Jump to bottom
Shine Akhanda edited this page Oct 29, 2026 · 3 revisions

Hearts Core Wiki

Welcome to the official Hearts Core documentation wiki. Hearts Core is a lightweight, high-performance Lifesteal plugin engineered specifically for Paper and Folia Minecraft servers.

Table of Contents

  1. Overview & Requirements
  2. Installation
  3. Commands & Permissions
  4. GUI System
  5. Configuration Guide
  6. Economy & Shop Integration
  7. Folia & Geyser Compatibility

Overview & Requirements

Hearts Core brings modern Lifesteal mechanics to your server with built-in GUI panels, economy integration, anti-farm protection, and combat logging checks.

Requirements

  • Server Platform: Paper, Folia, or compatible server software.
  • Java Version: Java 17 or higher.
  • Dependencies:
    • Vault API (Required for shop functionality)
    • Economy Provider (Required for shop functionality, e.g., EternalEconomy)

Installation

  1. Stop your server.
  2. Place HeartsCore.jar into your server's plugins/ directory.
  3. Ensure Vault and your preferred economy plugin (e.g., EternalEconomy) are installed in the plugins/ folder.
  4. Start your server to generate default configuration files (plugins/HeartsCore/config.yml).
  5. Configure config.yml according to your server preferences and restart or reload the configuration.

Commands & Permissions

Player Commands

  • /hc hearts Description: Displays your current and maximum heart count. Permission: heartscore.command.hearts

  • /hc withdraw Description: Withdraws hearts into physical item form. Permission: heartscore.command.withdraw

  • /hcgui Description: Opens the main interactive player GUI menu. Permission: heartscore.command.gui

  • /hshop Description: Opens the heart shop menu. Permission: heartscore.command.shop

Admin Commands

  • /hc admin hearts Description: Displays the heart count of a specified player. Permission: heartscore.admin.hearts

  • /hc admin add Description: Grants hearts to a specified player. Permission: heartscore.admin.add

  • /hc admin revoke Description: Takes hearts from a specified player. Permission: heartscore.admin.revoke

  • /hcgui admin Description: Opens the administrative management GUI. Permission: heartscore.admin.gui

GUI System

Hearts Core includes built-in menu interfaces for simplified management:

  • Player Main GUI (/hcgui): Displays current player statistics (Hearts, Kills, Deaths), quick heart withdrawal options, and navigation buttons for the shop.
  • Admin Panel GUI (/hcgui admin): Allows administrators to visually select online players and instantly add, remove, or reset their heart counts without needing text commands.
  • Heart Shop GUI (/hshop): Interface for purchasing extra hearts using server currency.

Configuration Guide

The main configuration file is located at plugins/HeartsCore/config.yml. All messages and titles support MiniMessage gradient and color formatting.

Config Breakdown

Core Settings

  • starting-hearts (Default: 10): Number of hearts a new player receives upon joining.
  • max-hearts (Default: 20): Maximum heart cap a player can reach.
  • min-hearts (Default: 0): Minimum heart threshold.
  • combat-tag-seconds (Default: 10): Time period after taking PvP damage during which environmental/trap deaths are credited to the attacker.

Anti-Farm Settings

anti-farm: enabled: true kill-cooldown-seconds: 300 block-same-ip: true

Prevents players from farming hearts off the same player repeatedly or using alt accounts on the same IP address.

PvP & Death Rules

pvp: mode: DROP # Modes: DROP (drops heart item) or DIRECT (adds directly to killer) heart-loss: 1 killer-gain: 1

natural-death: heart-loss: 0 drop-heart: false

Zero-Heart Policy

zero-heart: policy: ban # Policies: ban, kick, or spectator ban-reason: "You ran out of hearts." kick-reason: "You ran out of hearts." restore-gamemode: true

Economy & Shop Integration

Hearts Core integrates with Vault to process shop transactions.

To enable the shop:

  1. Ensure Vault and an economy provider (e.g., EternalEconomy) are active on the server.
  2. Set shop.enabled: true in config.yml.
  3. Configure offers under the shop.offers section:

shop: enabled: true offers: one: slot: 11 hearts: 1 price: 1000000.0 five: slot: 13 hearts: 5 price: 5000000.0 ten: slot: 15 hearts: 10 price: 10000000.0

Folia & Geyser Compatibility

  • Folia Support: Built with region-aware scheduling to support multi-threaded server execution without main-thread blocking.
  • Geyser (Bedrock) Support: Includes automated custom head texture handling (geyser.install-custom-skull: true) to display custom heart textures correctly for Bedrock Edition players.

Clone this wiki locally