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
