UltimateLifeSteal

** UltimateLifeSteal

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	✅ Full MiniMessage	❌ Limited
MySQL Support	✅ HikariCP Pool	❌ Often SQLite only
Anti-Counterfeit	✅ PDC Validation	❌ Easy to fake
WorldGuard	✅ Custom Flags	❌ Limited
Developer API	✅ Full API + Events	❌ None
Languages	✅ 13+ Languages	❌ English only

---

⭐ Key Features

💗 Heart Mechanics

• Configurable starting hearts: (Default: 10)
• Maximum heart limit: (Default: 20)
• Minimum hearts: (Default: 0 - leads to elimination)
• Fully Customizable: Set hearts gained/lost per kill or death.
• Visuals: Health bar updates in real-time.

⚔️ PvP Heart Stealing

• Instant Transfer: Kill a player to gain their heart instantly.
• Feedback: Satisfying sound effects, particles, and screen notifications.
• Statistics: Tracks Kills, Deaths, Hearts Stolen, and K/D Ratio.
• Anti-Abuse: Cooldowns for killing the same player repeatedly to prevent farming.

☠️ Elimination System
Choose what happens when a player reaches 0 hearts:

• Ban Mode (Default): Player is banned from the server until revived.
• Spectator Mode: Player becomes a spectator; can watch but not play.
• Kick Mode: Player is kicked and re-kicked on join.

💚 Revival System

• Revive Crystal: Craftable item to bring back eliminated players.
• GUI Selection: Inventory GUI to select who to revive.
• Confirmation: Built-in checks to prevent accidents.
• Broadcasts: Server-wide announcement when someone is revived.

📦 Heart Withdraw System

• Physical Hearts: Convert your hearts into tradeable items.
• Economy: Allows players to trade hearts as currency.
• Safety: Minimum heart protection prevents withdrawing if HP is too low.

🛡️ Game Rules & Balancing

• Disable Totems: Option to make Totems of Undying ineffective.
• Disable Crystals: Prevent End Crystal PvP.
• Heart Decay: Optional setting to lose hearts slowly over time.
• Disabled Worlds: Disable LifeSteal mechanics in specific worlds (e.g., Lobby).

🗄️ Database Support

• SQLite (Default): Zero config, perfect for single servers.
• MySQL / MariaDB: High performance, perfect for Bungee/Velocity networks.

---

🎯 How It Works

Basic Gameplay Flow

1. Player Joins: Starts with default hearts (e.g., 10 Hearts).
2. PvP Action:
   • If they Kill: They gain +1 Heart.
   • If they Die: They lose -1 Heart.
3. Elimination:
   • If hearts drop to 0, the player is Eliminated (Banned/Spectator).
4. Revival:
   • A teammate crafts a Revive Crystal.
   • They use the crystal to unban the eliminated player.
   • The player returns with default hearts.

Heart Economy

• Gaining: Kill players, use Heart Items, or Admin commands.
• Losing: Die to players, die to environment (optional), or withdraw hearts.
• Trading: Withdraw hearts into physical items to trade with others.

---

💻 Commands

Player Commands

Command	Description	Permission
/withdraw <amount>	Withdraw hearts into 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	ultimatelifesteal.recipes

Admin Commands

Command	Description	Permission
/uls help	Show help menu	ultimatelifesteal.admin
/uls sethearts <player> <amount>	Set a player's hearts	ultimatelifesteal.sethearts
/uls giveitem <type> [player]	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 configuration	ultimatelifesteal.reload

---

🔐 Permissions

Permission List

• ultimatelifesteal.admin - Gives access to all admin commands.
• ultimatelifesteal.withdraw - Allow withdrawing hearts.
• ultimatelifesteal.recipes - Allow viewing recipes.
• ultimatelifesteal.use.heart - Allow using heart items.
• ultimatelifesteal.use.revive - Allow using revive crystals.
• ultimatelifesteal.craft.heart - Allow crafting hearts.
• ultimatelifesteal.craft.revive - Allow crafting revive crystals.

Bypass Permissions

• ultimatelifesteal.bypass.max - Bypass max heart limit.
• ultimatelifesteal.bypass.elimination - Cannot be eliminated.
• ultimatelifesteal.bypass.heartloss - Does not lose hearts on death.

---

📊 Placeholders (PlaceholderAPI)

Basic Stats

Placeholder	Description
%ultimatelifesteal_hearts%	Current hearts
%ultimatelifesteal_max_hearts%	Maximum hearts allowed
%ultimatelifesteal_health%	Current health points
%ultimatelifesteal_kills%	Total kills
%ultimatelifesteal_deaths%	Total deaths
%ultimatelifesteal_kdr%	Kill/Death ratio

Leaderboards
Replace 1 with any rank number (1-100).

• %ultimatelifesteal_top_kills_1% - Name of 1 Killer
• %ultimatelifesteal_top_kills_1_value% - Kills of 1 Killer
• %ultimatelifesteal_top_hearts_1% - Name of player with most hearts
• %ultimatelifesteal_top_hearts_1_value% - Heart count of player

---

🎁 Custom Items & Crafting

❤️ Heart Item

• Usage: Right-click to consume and gain +1 Permanent Heart.
• Validation: Uses PersistentDataContainer (Players cannot fake hearts by renaming items in an anvil).

Default Recipe:

• Top Row: Diamond, Gold Block, Diamond
• Middle Row: Gold Block, Nether Star, Gold Block
• Bottom Row: Diamond, Gold Block, Diamond

✦ Revive Crystal

• Usage: Right-click to open the Revival Menu and bring back a banned player.

Default Recipe:

• Top Row: Emerald Block, Beacon, Emerald Block
• Middle Row: Totem of Undying, Nether Star, Totem of Undying
• Bottom Row: Emerald Block, Beacon, Emerald Block

> Note: All recipes are fully customizable in recipes.yml.

---

⚙️ Configuration

The plugin generates the following files:

• config.yml - Main settings.
• recipes.yml - Edit crafting recipes.
• languages/ - Translate messages (en-US, es-ES, de-DE, etc).

Example: Hearts Config

hearts:
  starting: 10
  max: 20
  min: 0
  per-kill: 1
  per-death: 1
  lose-on-natural-death: false
  lose-on-pvp-death: true

Example: Elimination Config

elimination:
  enabled: true
  action: ban   Options: ban, spectator, kick
  broadcast: true

---

📥 Installation

1. Download the JAR file.
2. Drag and drop it into your server's /plugins/ folder.
3. Restart your server.
4. Edit config.yml to your liking.
5. Run /uls reload to apply changes.

Requirements:

• Paper 1.21.1 or higher (Spigot is not supported due to modern API usage).
• Java 21 or higher.

---

Made with ❤️ for the Minecraft Community**