UltimateLifeSteal - Complete Plugin Documentation

---

```
╔═══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ██╗ ██╗██╗ ████████╗██╗███╗ ███╗ █████╗ ████████╗███████╗ ║
║ ██║ ██║██║ ╚══██╔══╝██║████╗ ████║██╔══██╗╚══██╔══╝██╔════╝ ║
║ ██║ ██║██║ ██║ ██║██╔████╔██║███████║ ██║ █████╗ ║
║ ██║ ██║██║ ██║ ██║██║╚██╔╝██║██╔══██║ ██║ ██╔══╝ ║
║ ╚██████╔╝███████╗██║ ██║██║ ╚═╝ ██║██║ ██║ ██║ ███████╗ ║
║ ╚═════╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚══════╝ ║
║ ║
║ ██╗ ██╗███████╗███████╗███████╗████████╗███████╗ █████╗ ██╗ ║
║ ██║ ██║██╔════╝██╔════╝██╔════╝╚══██╔══╝██╔════╝██╔══██╗██║ ║
║ ██║ ██║█████╗ █████╗ ███████╗ ██║ █████╗ ███████║██║ ║
║ ██║ ██║██╔══╝ ██╔══╝ ╚════██║ ██║ ██╔══╝ ██╔══██║██║ ║
║ ███████╗██║██║ ███████╗███████║ ██║ ███████╗██║ ██║███████╗ ║
║ ╚══════╝╚═╝╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝╚═╝ ╚═╝╚══════╝ ║
║ ║
║ The Ultimate LifeSteal SMP Experience ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
```

| Version | Minecraft | Java | API |
|---------|-----------|------|-----|
| 1.0.0 | 1.21.1 | 21+ | Paper |

---

📖 Description

**UltimateLifeSteal** is a comprehensive, feature-rich LifeSteal SMP plugin designed for Minecraft 1.21.1+ Paper servers. It transforms your survival server into an intense, high-stakes PvP experience where every kill matters and every death has permanent consequences.

What is LifeSteal?

LifeSteal is a popular SMP (Survival Multiplayer) game mode where:
- **Killing a player steals their hearts** - The killer gains permanent health
- **Dying loses hearts** - The victim loses permanent health
- **Reaching 0 hearts = Elimination** - Players are banned until revived
- **Revival is possible** - Teammates can craft special items to bring back eliminated players

Why Choose UltimateLifeSteal?

| Feature | UltimateLifeSteal | Other Plugins |
|---------|-------------------|---------------|
| Modern API | Paper 1.21.1 + Adventure | Outdated Bukkit |
| HEX Colors & Gradients | ✅ Full MiniMessage | ❌ Limited |
| MySQL Support | ✅ HikariCP Pool | ❌ Often SQLite only |
| Anti-Counterfeit Items | ✅ PDC Validation | ❌ Easy to fake |
| WorldGuard Integration | ✅ Custom Flags | ❌ Limited |
| Developer API | ✅ Full API + Events | ❌ None |
| Multi-Language | ✅ 13+ Languages | ❌ English only |
| Active Development | ✅ Regular Updates | ❌ Abandoned |

---

⭐ Key Features

💗 Heart System
```
┌─────────────────────────────────────────────────────────────┐
│ ❤️ HEART MECHANICS │
├─────────────────────────────────────────────────────────────┤
│ • Configurable starting hearts (default: 10) │
│ • Maximum heart limit (default: 20) │
│ • Minimum hearts before elimination (default: 0) │
│ • Hearts per kill/death fully customizable │
│ • Natural death heart loss (optional) │
│ • Visual health bar updates in real-time │
└─────────────────────────────────────────────────────────────┘
```

⚔️ PvP Heart Stealing
- **Instant Transfer**: Kill a player → Gain their heart instantly
- **Sound Effects**: Satisfying audio feedback for kills
- **Visual Effects**: Particle effects and screen notifications
- **Statistics Tracking**: Kills, deaths, hearts stolen/lost, K/D ratio
- **Anti-Abuse System**: Cooldown for same-player kills to prevent farming

☠️ Elimination System
```
┌─────────────────────────────────────────────────────────────┐
│ 💀 ELIMINATION OPTIONS │
├─────────────────────────────────────────────────────────────┤
│ │
│ BAN MODE (Default) │
│ └── Player is banned from server until revived │
│ │
│ SPECTATOR MODE │
│ └── Player becomes spectator, can watch but not play │
│ │
│ KICK MODE │
│ └── Player is kicked, will be re-kicked on rejoin │
│ │
└─────────────────────────────────────────────────────────────┘
```

💚 Revival System
- **Revive Crystal**: Craftable item to bring back eliminated players
- **GUI Selection**: Beautiful inventory GUI to select who to revive
- **Confirmation**: Confirmation dialog to prevent accidents
- **Broadcast**: Server-wide announcement when someone is revived
- **Cooldowns**: Configurable cooldown between revives

📦 Heart Withdraw System
- **Physical Hearts**: Convert your hearts into tradeable items
- **Economy Integration**: Trade hearts with other players
- **Minimum Protection**: Can't withdraw below safety threshold
- **Cooldowns**: Prevent spam withdrawing

🛡️ Game Rules & Balancing
```
┌─────────────────────────────────────────────────────────────┐
│ ⚖️ BALANCE OPTIONS │
├─────────────────────────────────────────────────────────────┤
│ │
│ ✗ Disable Totems of Undying │
│ └── Totems won't save you from death │
│ │
│ ✗ Disable End Crystal PvP │
│ └── Prevent crystal placement/damage │
│ │
│ ⏰ Heart Decay (Optional) │
│ └── Slowly lose hearts over time │
│ │
│ 🌍 Disabled Worlds │
│ └── Specify worlds where lifesteal doesn't apply │
│ │
│ 🔄 Anti-Abuse Cooldowns │
│ └── Prevent kill farming between same players │
│ │
└─────────────────────────────────────────────────────────────┘
```

🎨 Beautiful Messages
- **MiniMessage Support**: Full gradient, HEX, and formatting support
- **Customizable**: Every message can be edited
- **Multi-Language**: Support for 13+ languages
- **Titles & Action Bars**: Eye-catching notifications

🗄️ Database Support
```
┌─────────────────────────────────────────────────────────────┐
│ 💾 STORAGE OPTIONS │
├─────────────────────────────────────────────────────────────┤
│ │
│ SQLite (Default) │
│ ├── Zero configuration required │
│ ├── Perfect for single servers │
│ └── Data stored in plugins/UltimateLifeSteal/ │
│ │
│ MySQL / MariaDB │
│ ├── HikariCP connection pooling │
│ ├── Perfect for networks/bungee │
│ ├── High performance with caching │
│ └── Shared data across servers │
│ │
└─────────────────────────────────────────────────────────────┘
```

🔌 Plugin Integrations
| Plugin | Integration |
|--------|-------------|
| **PlaceholderAPI** | 20+ placeholders for hearts, kills, deaths, etc. |
| **WorldGuard** | Custom `prevent-lifesteal` flag for regions |
| **Vault** | Economy support for buying/selling hearts |
| **LuckPerms** | Full permission support |

---

🎯 How It Works

Basic Gameplay Flow

```
┌─────────────────┐
│ Player Joins │
│ (10 ❤️ Hearts) │
└────────┬────────┘
│
┌──────────────┴──────────────┐
│ │
▼ ▼
┌────────────────┐ ┌────────────────┐
│ Kills Player │ │ Gets Killed │
│ (+1 ❤️) │ │ (-1 ❤️) │
└───────┬────────┘ └───────┬────────┘
│ │
│ ▼
│ ┌────────────────┐
│ │ Hearts > 0? │
│ └───────┬────────┘
│ YES │ NO
│ ┌─────────────┴─────────────┐
│ │ │
│ ▼ ▼
│ ┌────────────────┐ ┌────────────────┐
│ │ Respawns │ │ ELIMINATED │
│ │ (Fewer Hearts)│ │ (Banned) │
│ └────────────────┘ └───────┬────────┘
│ │
│ ▼
│ ┌────────────────┐
│ │ Needs Revival │
│ │ (Revive Crystal)│
│ └───────┬────────┘
│ │
│ ▼
│ ┌────────────────┐
│ │ Revived! │
│ │ (10 ❤️ Hearts) │
└───────────────────────────────┴────────────────┘
```

Heart Economy

```
┌─────────────────────────────────────────────────────────────────┐
│ HEART ECONOMY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ GAINING HEARTS: │
│ ├── 🗡️ Kill another player (+1 heart per kill) │
│ ├── 📦 Use Heart item (+1 heart per item) │
│ └── 🔧 Admin command (/uls sethearts) │
│ │
│ LOSING HEARTS: │
│ ├── 💀 Die to another player (-1 heart per death) │
│ ├── 🌋 Die to environment (optional, configurable) │
│ ├── 📤 Withdraw hearts (/withdraw) │
│ └── ⏰ Heart decay over time (optional) │
│ │
│ TRADING HEARTS: │
│ ├── 📤 Withdraw hearts to physical items │
│ ├── 🤝 Trade items with other players │
│ └── 📥 Consume heart items to gain hearts │
│ │
└─────────────────────────────────────────────────────────────────┘
```

---

💻 Commands

Player Commands

| Command | Description | Permission |
|---------|-------------|------------|
| `/withdraw <amount>` | Withdraw hearts into physical items | `ultimatelifesteal.withdraw` |
| `/hearts` | View your current heart count | `ultimatelifesteal.hearts` |
| `/hearts <player>` | View another player's hearts | `ultimatelifesteal.hearts.others` |
| `/recipes` | Open custom recipe viewer GUI | `ultimatelifesteal.recipes` |

Admin Commands

| Command | Description | Permission |
|---------|-------------|------------|
| `/uls help [page]` | Show help menu | `ultimatelifesteal.admin` |
| `/uls sethearts <player> <amount>` | Set a player's hearts | `ultimatelifesteal.sethearts` |
| `/uls giveitem <type> [player] [amount]` | Give custom items | `ultimatelifesteal.giveitem` |
| `/uls revive <player>` | Revive an eliminated player | `ultimatelifesteal.revive` |
| `/uls reset <player>` | Reset a player's data | `ultimatelifesteal.reset` |
| `/uls reload` | Reload plugin configuration | `ultimatelifesteal.reload` |

Command Examples

```bash
Withdraw 3 hearts into items
/withdraw 3

Give yourself 5 heart items
/uls giveitem heart 5

Give a player a revive crystal
/uls giveitem revive PlayerName 1

Set a player to 15 hearts
/uls sethearts PlayerName 15

Revive an eliminated player
/uls revive EliminatedPlayer

Reset a player's data (requires confirmation)
/uls reset PlayerName
/uls reset PlayerName confirm

Reload configuration
/uls reload
```

---

🔐 Permissions

Permission Tree

```
ultimatelifesteal.* (All permissions)
├── ultimatelifesteal.admin (All admin commands)
│ ├── ultimatelifesteal.sethearts (Set hearts command)
│ ├── ultimatelifesteal.giveitem (Give items command)
│ ├── ultimatelifesteal.revive (Revive command)
│ ├── ultimatelifesteal.reset (Reset command)
│ ├── ultimatelifesteal.reload (Reload command)
│ └── ultimatelifesteal.eliminate (Eliminate command)
│
├── ultimatelifesteal.withdraw (Withdraw hearts)
├── ultimatelifesteal.recipes (View recipes GUI)
├── ultimatelifesteal.hearts (View own hearts)
├── ultimatelifesteal.hearts.others (View others' hearts)
│
├── ultimatelifesteal.use.heart (Use heart items)
├── ultimatelifesteal.use.revive (Use revive crystals)
├── ultimatelifesteal.craft.heart (Craft heart items)
├── ultimatelifesteal.craft.revive (Craft revive crystals)
│
└── ultimatelifesteal.bypass.* (All bypasses)
├── ultimatelifesteal.bypass.max (Bypass max hearts)
├── ultimatelifesteal.bypass.elimination (Can't be eliminated)
├── ultimatelifesteal.bypass.heartloss (Don't lose hearts)
├── ultimatelifesteal.bypass.cooldown (Bypass cooldowns)
├── ultimatelifesteal.bypass.totem (Totems work)
└── ultimatelifesteal.bypass.crystal (Crystals work)
```

Permission Defaults

| Permission | Default |
|------------|---------|
| `ultimatelifesteal.admin` | OP |
| `ultimatelifesteal.withdraw` | Everyone |
| `ultimatelifesteal.recipes` | Everyone |
| `ultimatelifesteal.hearts` | Everyone |
| `ultimatelifesteal.bypass.*` | OP |

---

📊 Placeholders (PlaceholderAPI)

Basic Placeholders

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `%ultimatelifesteal_hearts%` | Current hearts | `15` |
| `%ultimatelifesteal_max_hearts%` | Maximum hearts allowed | `20` |
| `%ultimatelifesteal_min_hearts%` | Minimum hearts | `0` |
| `%ultimatelifesteal_starting_hearts%` | Starting hearts | `10` |
| `%ultimatelifesteal_health%` | Current health points | `30` |
| `%ultimatelifesteal_max_health%` | Max health points | `40` |

Statistics Placeholders

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `%ultimatelifesteal_kills%` | Total kills | `25` |
| `%ultimatelifesteal_deaths%` | Total deaths | `12` |
| `%ultimatelifesteal_kdr%` | Kill/Death ratio | `2.08` |
| `%ultimatelifesteal_hearts_stolen%` | Hearts stolen from others | `25` |
| `%ultimatelifesteal_hearts_lost%` | Hearts lost to others | `12` |
| `%ultimatelifesteal_net_hearts%` | Net hearts (stolen - lost) | `13` |

Status Placeholders

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `%ultimatelifesteal_eliminated%` | Is player eliminated? | `Yes` / `No` |
| `%ultimatelifesteal_eliminated_bool%` | Boolean eliminated | `true` / `false` |
| `%ultimatelifesteal_rank_kills%` | Rank by kills | `5` |
| `%ultimatelifesteal_rank_hearts%` | Rank by hearts | `3` |

Server Placeholders

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `%ultimatelifesteal_total_players%` | Total players in database | `150` |
| `%ultimatelifesteal_total_eliminated%` | Total eliminated players | `23` |

Leaderboard Placeholders

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `%ultimatelifesteal_top_kills_1%` | 1 killer name | `ProPlayer` |
| `%ultimatelifesteal_top_kills_1_value%` | 1 killer kills | `50` |
| `%ultimatelifesteal_top_hearts_1%` | 1 hearts name | `HeartKing` |
| `%ultimatelifesteal_top_hearts_1_value%` | 1 hearts count | `20` |

*Note: Replace `1` with any number 1-100 for different rankings*

---

🎁 Custom Items

❤️ Heart Item

```
┌─────────────────────────────────────────────────────────────┐
│ ❤️ HEART │
├─────────────────────────────────────────────────────────────┤
│ │
│ Material: Nether Star (with enchantment glint) │
│ │
│ Usage: Right-click to consume │
│ Effect: +1 permanent heart │
│ │
│ Obtain via: │
│ ├── Crafting (see recipe below) │
│ ├── /withdraw command │
│ └── Admin /uls giveitem heart │
│ │
│ Trading: Yes - can be traded between players │
│ Stackable: Yes - up to 64 │
│ │
│ Anti-Counterfeit: Uses PersistentDataContainer │
│ (Players cannot fake hearts with anvil renaming) │
│ │
└─────────────────────────────────────────────────────────────┘
```

✦ Revive Crystal

```
┌─────────────────────────────────────────────────────────────┐
│ ✦ REVIVE CRYSTAL │
├─────────────────────────────────────────────────────────────┤
│ │
│ Material: Beacon (with enchantment glint) │
│ │
│ Usage: Right-click to open revival GUI │
│ Effect: Revives one eliminated player │
│ │
│ Obtain via: │
│ ├── Crafting (see recipe below) │
│ └── Admin /uls giveitem revive │
│ │
│ Consumed: Yes - one crystal per revival │
│ Stackable: Yes - up to 64 │
│ │
│ When used: │
│ 1. Opens GUI showing all eliminated players │
│ 2. Click on player to select them │
│ 3. Confirm revival │
│ 4. Crystal is consumed │
│ 5. Player is unbanned with starting hearts │
│ │
└─────────────────────────────────────────────────────────────┘
```

---

🔨 Crafting Recipes

Heart Item Recipe (Default)

```
┌─────────────────────────────────────────────────────────────┐
│ HEART RECIPE │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────┬─────┬─────┐ ┌─────┐ │
│ │ 💎 │ 🟨 │ 💎 │ │ │ │
│ ├─────┼─────┼─────┤ │ ⭐ │ │
│ │ 🟨 │ ⭐ │ 🟨 │ ═══> │ │ │
│ ├─────┼─────┼─────┤ │ ❤️ │ │
│ │ 💎 │ 🟨 │ 💎 │ │ │ │
│ └─────┴─────┴─────┘ └─────┘ │
│ │
│ 💎 = Diamond (x4) │
│ 🟨 = Gold Block (x4) │
│ ⭐ = Nether Star (x1) │
│ │
│ Total Cost: │
│ • 4 Diamonds │
│ • 4 Gold Blocks (36 Gold Ingots) │
│ • 1 Nether Star (Wither Kill) │
│ │
└─────────────────────────────────────────────────────────────┘
```

Revive Crystal Recipe (Default)

```
┌─────────────────────────────────────────────────────────────┐
│ REVIVE CRYSTAL RECIPE │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────┬─────┬─────┐ ┌─────┐ │
│ │ 💚 │ 🔷 │ 💚 │ │ │ │
│ ├─────┼─────┼─────┤ │ 🔷 │ │
│ │ 🛡️ │ ⭐ │ 🛡️ │ ═══> │ │ │
│ ├─────┼─────┼─────┤ │ ✦ │ │
│ │ 💚 │ 🔷 │ 💚 │ │ │ │
│ └─────┴─────┴─────┘ └─────┘ │
│ │
│ 💚 = Emerald Block (x4) │
│ 🔷 = Beacon (x2) │
│ 🛡️ = Totem of Undying (x2) │
│ ⭐ = Nether Star (x1) │
│ │
│ Total Cost: │
│ • 4 Emerald Blocks (36 Emeralds) │
│ • 2 Beacons (2 Wither Kills + glass + obsidian) │
│ • 2 Totems of Undying (Evoker/Raid drops) │
│ • 1 Nether Star (Wither Kill) │
│ │
└─────────────────────────────────────────────────────────────┘
```

Alternative Recipes

The plugin includes several alternative recipes that can be enabled in `recipes.yml`:

| Recipe | Difficulty | Key Difference |
|--------|------------|----------------|
| `heart-easy` | Easy | Only gold ingots + nether star |
| `heart-medium` | Medium | Uses enchanted golden apple |
| `heart-expensive` | Very Hard | 8 diamond blocks |
| `heart-netherite` | Extreme | Netherite + ancient debris |
| `revive-crystal-easy` | Medium | Diamonds instead of emeralds |
| `revive-crystal-extreme` | Extreme | Requires dragon egg |

---

⚙️ Configuration

Configuration Files

```
plugins/UltimateLifeSteal/
├── config.yml Main configuration
├── recipes.yml Custom crafting recipes
├── playerdata.db SQLite database (if using SQLite)
└── languages/
├── en-US.yml English (default)
├── es-ES.yml Spanish
├── de-DE.yml German
├── fr-FR.yml French
├── pt-BR.yml Portuguese
├── zh-CN.yml Chinese
├── ja-JP.yml Japanese
├── ko-KR.yml Korean
├── ru-RU.yml Russian
├── it-IT.yml Italian
├── pl-PL.yml Polish
├── nl-NL.yml Dutch
└── tr-TR.yml Turkish
```

Now you can create unlimited custom recipes just by editing recipes.yml! 🎉

Feature Supported
Custom recipe names ✅ Yes
Enable/disable recipes ✅ Yes
Shaped recipes ✅ Yes
Shapeless recipes ✅ Yes
Custom ingredients ✅ Yes
Custom amounts ✅ Yes
Multiple recipes per item ✅ Yes
Hot-reload recipes ✅ Yes (/uls reload)
Recipe discovery ✅ Yes
Crafting cooldowns ✅ Yes
Daily limits ✅ Yes

Key Configuration Sections

Hearts Configuration
```yaml
hearts:
starting: 10 Starting hearts for new players
max: 20 Maximum hearts allowed
min: 0 Minimum before elimination
per-kill: 1 Hearts gained per kill
per-death: 1 Hearts lost per death
lose-on-natural-death: false Lose hearts to environment?
lose-on-pvp-death: true Lose hearts to players?
```

Elimination Configuration
```yaml
elimination:
enabled: true
action: ban "ban", "spectator", or "kick"
broadcast: true Announce eliminations?
message: |
<red><bold>YOU HAVE BEEN ELIMINATED!</bold></red>
<gray>You must be revived to play again.</gray>
```

Database Configuration
```yaml
database:
type: sqlite "sqlite" or "mysql"
mysql:
host: localhost
port: 3306
database: ultimatelifesteal
username: root
password: ""
pool-size: 10
```

Game Rules
```yaml
game-rules:
disable-totems: false
disable-end-crystals:
placement: false
damage: false
disabled-worlds:
- "lobby"
- "spawn"
```

---

📥 Installation

Requirements

- **Server**: Paper 1.21.1+ (or forks like Purpur)
- **Java**: Java 21 or higher
- **RAM**: Minimum 2GB recommended

Step-by-Step Installation

```
1. DOWNLOAD
└── Download UltimateLifeSteal-1.0.0.jar from releases

2. INSTALL
└── Place JAR in your server's /plugins/ folder

3. RESTART
└── Restart your server (not /reload)

4. CONFIGURE
└── Edit plugins/UltimateLifeSteal/config.yml

5. RELOAD (Optional)
└── Use /uls reload to apply changes
```

First-Time Setup Checklist

```
☐ Installed on Paper 1.21.1+
☐ Java 21 installed
☐ Server restarted after install
☐ Configured starting/max hearts
☐ Set elimination action (ban/spectator/kick)
☐ Tested heart stealing works
☐ Tested crafting recipes work
☐ Set up permissions for staff
☐ Optional: Installed PlaceholderAPI
☐ Optional: Installed WorldGuard
☐ Optional: Set up MySQL for network
```

---

🔗 Dependencies

Required
- **Paper 1.21.1+** - Server software

Optional (Recommended)
| Plugin | Purpose | Link |
|--------|---------|------|
| PlaceholderAPI | Placeholder support | [SpigotMC](https://www.spigotmc.org/resources/placeholderapi.6245/) |
| WorldGuard | Region protection | [EngineHub](https://enginehub.org/worldguard) |
| Vault | Economy integration | [GitHub](https://github.com/MilkBowl/Vault) |
| LuckPerms | Permission management | [LuckPerms](https://luckperms.net/) |

---

👨‍💻 API for Developers

Maven/Gradle Dependency

```kotlin
// build.gradle.kts
repositories {
maven("https://jitpack.io")
}

dependencies {
compileOnly("com.github.ultimatelifesteal:ultimatelifesteal:1.0.0")
}
```

```xml

<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>

<dependency>
<groupId>com.github.ultimatelifesteal</groupId>
<artifactId>ultimatelifesteal</artifactId>
<version>1.0.0</version>
<scope>provided</scope>
</dependency>
```

API Usage Examples

```java
// Get the API instance
LifeStealAPI api = UltimateLifeSteal.getInstance().getAPI();

// Get player hearts
int hearts = api.getHearts(player);

// Set player hearts
api.setHearts(player, 15);

// Add hearts
int newHearts = api.addHearts(player, 5);

// Remove hearts
int newHearts = api.removeHearts(player, 3);

// Check if player is eliminated
boolean eliminated = api.isEliminated(player.getUniqueId());

// Revive a player
api.revivePlayer(uuid, reviverUuid).thenAccept(success -> {
if (success) {
System.out.println("Player revived!");
}
});

// Get player statistics
int kills = api.getKills(uuid);
int deaths = api.getDeaths(uuid);
double kdr = api.getKDR(uuid);
```

Custom Events

```java
// Listen for heart gain
@EventHandler
public void onHeartGain(HeartGainEvent event) {
Player player = event.getPlayer();
int gained = event.getHeartsGained();

// Cancel the event to prevent heart gain
// event.setCancelled(true);

// Modify hearts gained
event.setHeartsGained(gained * 2); // Double hearts!
}

// Listen for elimination
@EventHandler
public void onElimination(PlayerEliminatedEvent event) {
Player player = event.getPlayer();
Player killer = event.getKiller(); // Can be null

// Custom ban message
event.setBanMessage("<red>You died to " + killer.getName() + "!</red>");

// Cancel to prevent elimination
// event.setCancelled(true);
}

// Listen for revival
@EventHandler
public void onRevive(PlayerRevivedEvent event) {
UUID revivedUuid = event.getRevivedPlayerUUID();
Player reviver = event.getReviver(); // Can be null for admin revive

// Modify hearts given on revive
event.setHeartsToSet(5); // Start with 5 hearts instead
}
```

Available Events

| Event | Description | Cancellable |
|-------|-------------|-------------|
| `HeartGainEvent` | Player gains hearts | ✅ |
| `HeartLoseEvent` | Player loses hearts | ✅ |
| `PlayerEliminatedEvent` | Player eliminated | ✅ |
| `PlayerRevivedEvent` | Player revived | ✅ |

---

❓ Frequently Asked Questions

General Questions

**Q: Does this work with Spigot?**
> A: No, this plugin requires Paper 1.21.1+ due to Adventure API usage.

**Q: Can I use this on a Bungeecord/Velocity network?**
> A: Yes! Use MySQL database and install on all survival servers.

**Q: Will this reset player hearts after update?**
> A: No, all data is stored in the database and persists through updates.

**Q: Can players fake heart items?**
> A: No! Items are validated using PersistentDataContainer (PDC) which cannot be edited by players.

Configuration Questions

**Q: How do I disable natural death heart loss?**
```yaml
hearts:
lose-on-natural-death: false
```

**Q: How do I make totems still work?**
```yaml
game-rules:
disable-totems: false
```

**Q: How do I set up a lobby where hearts don't apply?**
```yaml
game-rules:
disabled-worlds:
- "lobby"
- "hub"
```

**Q: How do I use MySQL instead of SQLite?**
```yaml
database:
type: mysql
mysql:
host: localhost
port: 3306
database: ultimatelifesteal
username: your_user
password: your_password
```

Troubleshooting

**Q: Players aren't losing/gaining hearts!**
> Check:
> 1. Is the world in `disabled-worlds`?
> 2. Does the player have `bypass.heartloss` permission?
> 3. Is WorldGuard's `prevent-lifesteal` flag set?
> 4. Check console for errors.

**Q: Heart items don't work!**
> Make sure:
> 1. Player has `ultimatelifesteal.use.heart` permission
> 2. Item is a genuine plugin item (not anvil-renamed)
> 3. Player isn't at max hearts

**Q: Eliminated players can still join!**
> Check:
> 1. `elimination.enabled` is `true`
> 2. `elimination.action` is set to `ban`
> 3. Use `/uls revive <player>` to manually test

---

Before Asking for Help

1. ✅ Check you're using Paper 1.21.1+
2. ✅ Check you're using Java 21+
3. ✅ Read this documentation
4. ✅ Check console for errors
5. ✅ Try `/uls reload` first
6. ✅ Search existing GitHub issues

Reporting Bugs

When reporting bugs, please include:
- Server version (`/version`)
- Plugin version
- Full error from console
- Steps to reproduce
- Configuration files (remove sensitive data)

---

🙏 Credits

- **Paper Team** - For the amazing Paper API
- **Kyori** - For Adventure/MiniMessage
- **PlaceholderAPI Team** - For PAPI
- **WorldGuard Team** - For region protection API
- **All Contributors** - For testing and suggestions

---

⭐ Like This Plugin?

If you enjoy UltimateLifeSteal, please:
- 📝 Leave a review
- 🐛 Report bugs to help improve
- 💡 Suggest features
- 🤝 Contribute code

---

```
╔═══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ Thank you for using ║
║ ║
║ ULTIMATE LIFESTEAL ║
║ ║
║ Made with ❤️ for the Minecraft community ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
```

Need a server to run UltimateLifeSteal?
Get 24/7 high-performance hosting from reliable hosting for your community!
Click here to get started with KCB Hosting