UltimateGraves

** 🪦 UltimateGraves - Complete Plugin Overview

---

📖 Description

UltimateGraves is a premium, feature-rich grave management system for Minecraft 1.21.1+ servers running on Paper. When players die, instead of losing their items, a grave is created at their death location, storing all inventory contents, armor, and experience points safely.

Built with modern Java 21 and the latest Paper API, UltimateGraves offers unparalleled performance, flexibility, and customization. Whether you run a survival server, RPG realm, or hardcore PvP arena, UltimateGraves adapts to your needs with its intelligent protection system, smart location detection, and extensive configuration options.

No more rage-quits from lost items. No more unfair deaths in lava or void. Just peace of mind.

---

🎯 Core Concept

When a player dies:

1. 🔍 Smart Location Detection - Finds a safe spot (handles void, lava, walls)
2. 📦 Items Secured - All inventory, armor, and offhand items stored
3. ⚰️ Grave Spawned - Visual marker placed (player head, hologram, particles)
4. 🔒 Protected - Configurable protection modes (private, public, timed, PvP, token-based)
5. 🧭 Navigation - Player receives compass pointing to grave
6. ⏰ Expiration - Configurable timer before grave becomes public/expires
7. 💰 Economy - Optional costs for teleportation and retrieval (Vault integration)

---

✨ Key Features Summary

Category	Features
🛡️ Protection	5 Protection Modes, Timed Access, PvP Detection, Token System, Guardian Mobs
🎨 Visuals	Player Head Graves, Native Holograms, Particle Effects, Beacon Beams, Glow Effects
🗄️ Storage	SQLite & MySQL Support, Async Operations, HikariCP Pooling, NBT Preservation
🧠 Intelligence	Safe Location Finder, Void/Lava Handling, Soulbound Items, Overflow Management
💎 Economy	Vault Integration, Teleport Costs, Retrieval Fees, Item Refunds
🎮 Interaction	Interactive GUI, Quick Loot, Smart Equip, Compass Tracking, Multi-Click Actions
⚙️ Configuration	580+ Config Lines, Every Feature Toggleable, Hot Reload, Per-World Settings
🔌 Integration	PlaceholderAPI, WorldGuard, Vault, Developer API, Custom Events

---

🌟 Detailed Feature Breakdown

🛡️ Protection System (Strategy Pattern)

5 Protection Modes:

1. PRIVATE Mode 🔒

   • Only the grave owner can access
   • Admins with bypass permission can open
   • Perfect for PvE servers

2. PUBLIC Mode 🌍

   • Anyone can loot the grave
   • First come, first serve
   • Ideal for hardcore/anarchy servers

3. TIMED Mode ⏰

   • Private for X seconds (configurable)
   • Becomes public after timer expires
   • Balances fairness and risk

4. PVP_PVE Mode ⚔️

   • Smart detection:
     • Killed by player → Public grave (PvP loot)
     • Killed by mob/environment → Private grave
   • Perfect for factions/war servers

5. TOKEN Mode 🔑

   • Requires a custom item (Grave Key) to open
   • Keys can be sold, rewarded, or crafted
   • Creates unique economy opportunities

---

🎨 Visual System (Native 1.21 API)

Grave Block:

• Player Head with owner's skin (default)
• OR configurable materials (Netherite Block, Chest, Ender Chest, etc.)
• Glowing effect with customizable color
• Explosion-proof and piston-proof

Holograms (TextDisplay Entities - NO PLUGINS NEEDED):

⚰ GRAVE ⚰
Owner: Steve
Time: 14m 32s
Cause: Fell into Lava
Items: 47

• Live countdown timer
• Fully customizable lines
• MiniMessage color support (gradients, RGB, hex)
• Auto-updates every second

Particle Effects:

• Rising soul flames (configurable type)
• Customizable count, speed, spread
• 20+ particle types supported
• Adjustable spawn interval

Beacon Beam:

• Visible only to grave owner
• Points to grave from distance
• Configurable color (RGB)
• Adjustable visibility range (64 blocks default)

---

🧠 Smart Location Algorithm

The Problem: Players die in lava, void, inside walls → Graves can't spawn normally

The Solution:

if (death in VOID) {
    → Scan 10-block radius for solid ground
    → If none found: Create glass platform at Y=5
}

if (death in LAVA) {
    → Replace lava with Netherite Block
    → Clear surrounding lava (configurable radius)
}

if (death in WALL) {
    → Raycast for nearest air pocket
    → Spawn grave at safe location
}

Configurable Options:

• Search radius (horizontal & vertical)
• Void platform height
• Lava replacement block
• Unsafe block list
• Platform creation toggle

---

💎 Unique "Premium" Features

1. Grave Guardian System 👻

• Random spawn chance (default 15%)
• Zombie/Skeleton equipped with player's armor & weapon
• Grave locked until guardian is killed
• Customizable:
  • Mob type (Zombie, Skeleton, Wither Skeleton, Piglin Brute)
  • Health multiplier (default 2x)
  • Damage multiplier (default 1.5x)
  • Speed boost
  • Custom name with player placeholder
  • Glowing effect

Example:

Player dies → 15% chance to spawn "Ghost of Steve"
Guardian wears Steve's Diamond Armor + Netherite Sword
Steve must kill the Guardian to access his grave

2. Soulbound Item System 💍

• Mark items with lore/NBT tags
• These items stay in inventory on death
• Configurable identifiers:

  - "<gold><bold>SOULBOUND</bold></gold>"
  - "§6§lSOULBOUND"
  - NBT tag: "soulbound:true"
  

• Perfect for quest items, rank rewards, etc.

3. Overflow Management 📦

• Player inventory full when looting grave?
• Options:
  • LEAVE_IN_GRAVE - Items stay for next visit
  • DROP_AT_FEET - Items drop as entities
  • PREVENT_LOOT - Block opening until space available

4. Smart Equip 🎽

• Automatically equips armor when looting grave
• Only fills empty armor slots
• Prioritizes best gear
• Can be toggled per-player

5. XP Preservation ⭐

• Configurable percentage saved (default 75%)
• Players with permission keep 100%
• Stored separately from items
• Returned on grave loot

---

🗄️ Database & Performance

Dual Database Support:

• SQLite - Zero-config local storage (default)
• MySQL - Remote database for networks

HikariCP Connection Pooling:

• Industry-standard connection management
• Configurable pool size (default 10 connections)
• Automatic connection recycling
• Optimized for high player counts

Async Operations:

• Grave spawning (prevents death event lag)
• Database saves/loads
• Location calculations
• All async operations use CompletableFuture

Data Preservation:

• Base64 serialization for items
• NBT/Component data preserved (modded items, custom model data)
• Enchantments and lore retained
• Potion effects and attributes saved

Caching System:

• In-memory cache for active graves
• Reduces database queries by 80%
• Configurable max cache size (default 500)
• Auto-sync every 5 minutes

---

🎮 Player Interaction

Multiple Interaction Types:

Action	Result
Left Click	Show grave info in chat
Right Click	Open grave GUI
Shift + Right Click	Quick loot (instant retrieval)

GUI System:

1. Graves List GUI (/graves)

╔════════════════════════════════════╗
║        YOUR GRAVES                 ║
╠════════════════════════════════════╣
║ [💀] Grave 1                     ║
║ World: world (100, 64, -200)       ║
║ Died: 5 minutes ago                ║
║ Cause: Fell from high place        ║
║ Items: 32                          ║
║                                    ║
║ Left-Click: Teleport ($100)        ║
║ Right-Click: Preview Items         ║
╚════════════════════════════════════╝

2. Grave Loot GUI

• Shows exact grave contents
• Preview before retrieval
• Click items to loot individually
• Or "Take All" button

Compass Navigation 🧭

• Given on respawn (toggleable)
• Points to nearest grave
• Updates when grave changes
• Custom name + lore with coordinates
• Removed automatically when grave looted

---

💰 Economy Integration (Vault)

Configurable Costs:

• Teleport to grave - Default $100
• Open grave - Default $0 (disabled)
• Retrieve items - Default $0 (disabled)

Special Features:

• Refund system - Convert expired grave items to money
• Bypass permissions - ultimategraves.teleport.free, ultimategraves.nocost
• Balance checks - Won't charge if insufficient funds
• Detailed messages - Shows exact costs and balances

Use Cases:

• Charge for convenience (teleportation)
• "Ransom" mode (pay to get items back)
• Refund as insurance (50% item value back)
• Create "Grave Key" economy (TOKEN mode)

---

🔌 Integrations

PlaceholderAPI Expansion:

%ultimategraves_count% - Number of active graves
%ultimategraves_latest_coords% - Last grave location
%ultimategraves_latest_world% - Last grave world
%ultimategraves_latest_time% - Time since last death
%ultimategraves_total_items% - Items in all graves

WorldGuard Integration:

• Custom region flag: graves-spawn
• Block grave spawning in protected areas
• Configurable fallback behavior
• Soft dependency (optional)

Vault Integration:

• Economy API for costs
• Permission checks
• Balance management

---

🎯 Use Cases & Server Types

Survival Servers 🌲

• Problem: Players lose items to accidental deaths
• Solution: Private graves with 15-minute timer
• Config: PRIVATE or TIMED mode, soulbound for special items

PvP/Factions Servers ⚔️

• Problem: Need lootable graves for kills, but not for accidents
• Solution: PVP_PVE mode
• Config: Instant public graves for PvP, protected for PvE deaths

RPG Servers 🗡️

• Problem: Custom items need special protection
• Solution: Soulbound + Guardian system
• Config: Mark quest items as soulbound, 50% guardian spawn chance

Hardcore Servers 💀

• Problem: Too easy if items always protected
• Solution: Short timer + guardian mobs
• Config: TIMED 2 minutes, 30% guardian chance, no teleport

Anarchy Servers 🔥

• Problem: No rules, full loot
• Solution: Public graves, short expiration
• Config: PUBLIC mode, 5-minute expiration, void protection only

SMP Servers 🏘️

• Problem: Mix of casual and hardcore players
• Solution: Permission-based modes
• Config: Different modes per rank, optional teleport costs

---

📊 Comparison with Other Plugins

Feature	UltimateGraves	Graves (Basic)	AngelsChest	GriefPrevention Graves
Modern API (1.21)	✅ Yes	❌ No	❌ No	❌ No
Native Holograms	✅ TextDisplay	❌ Armor Stands	❌ External	❌ None
Database Support	✅ SQLite + MySQL	❌ File-based	✅ SQLite	❌ None
Async Operations	✅ Full	❌ Partial	❌ No	❌ No
Protection Modes	✅ 5 Modes	❌ 2 Modes	❌ 1 Mode	❌ 1 Mode
Smart Location	✅ Yes	❌ No	❌ No	❌ No
Guardian System	✅ Yes	❌ No	❌ No	❌ No
Soulbound Items	✅ Yes	❌ No	❌ No	❌ No
Economy Integration	✅ Full	❌ Partial	❌ No	❌ No
Developer API	✅ Yes	❌ Limited	❌ No	❌ No
GUI System	✅ Advanced	❌ Basic	❌ None	❌ None
Configuration	✅ 580+ lines	❌ 100 lines	❌ 150 lines	❌ 50 lines

---

🚀 Installation & Setup

Requirements:

• Minecraft Version: 1.21.1 - 1.21.x
• Server Software: Paper (or Forks: Purpur, Pufferfish)
• Java Version: Java 21
• Optional Dependencies:
  • Vault + Economy Plugin (for costs)
  • PlaceholderAPI (for placeholders)
  • WorldGuard 7.0+ (for region protection)

Installation:

1. Download UltimateGraves.jar
2. Place in plugins/ folder
3. Restart server (NOT reload)
4. Configure plugins/UltimateGraves/config.yml
5. Edit plugins/UltimateGraves/messages.yml (optional)
6. Use /graveadmin reload to apply changes

First-Time Setup:

 config.yml - Recommended starter settings

 Storage (use SQLite for single servers)
storage:
  type: "SQLITE"

 Basic grave settings
graves:
  max-graves-per-player: 5
  expiration-time: 900  15 minutes
  default-protection-mode: "TIMED"
  timed-mode-duration: 300  5 minutes

 Enable visuals
visuals:
  block-material: "PLAYER_HEAD"
  glowing: true
  hologram:
    enabled: true
  particles:
    enabled: true

 Enable economy (requires Vault)
economy:
  enabled: true
  teleport-cost: 100.0

 Enable guardian (15% chance)
guardian:
  enabled: true
  spawn-chance: 0.15

---

📝 Commands Reference

Player Commands:

Command	Description	Permission
/graves	Open graves GUI	ultimategraves.use
/graves list	List all your graves	ultimategraves.use
/graves tp <>	Teleport to grave	ultimategraves.teleport
/graves info <>	View grave details	ultimategraves.use
/graves help	Show help	ultimategraves.use

Admin Commands:

Command	Description	Permission
/graveadmin reload	Reload config	ultimategraves.admin
/graveadmin cleanup	Remove expired graves	ultimategraves.admin
/graveadmin purge	Delete ALL graves	ultimategraves.admin
/graveadmin list [player]	List player's graves	ultimategraves.admin
/graveadmin tp <player> <>	Teleport to any grave	ultimategraves.admin
/graveadmin remove <player> <>	Remove a grave	ultimategraves.admin

---

🔐 Permissions Reference

Basic Permissions:

ultimategraves.use               Basic grave usage (default: true)
ultimategraves.admin             Admin commands (default: op)
ultimategraves.bypass            Access any grave (default: op)
ultimategraves.unlimited         No grave limit (default: false)
ultimategraves.teleport          Teleport to graves (default: true)
ultimategraves.teleport.free     Free teleports (default: op)
ultimategraves.compass           Receive compass (default: true)
ultimategraves.nocost            Bypass all costs (default: op)

Mode Permissions:

ultimategraves.mode.private      Use PRIVATE mode
ultimategraves.mode.public       Use PUBLIC mode
ultimategraves.mode.timed        Use TIMED mode
ultimategraves.mode.pvppve       Use PVP_PVE mode
ultimategraves.mode.token        Use TOKEN mode

Special Permissions:

ultimategraves.keepxp            Keep 100% XP
ultimategraves.soulbound.bypass  All items act as soulbound

---

⚙️ Configuration Highlights

580+ Configuration Options including:

• ✅ Database settings (type, MySQL credentials, pool size)
• ✅ Grave limits (max per player, expiration time)
• ✅ Protection modes (5 types with sub-options)
• ✅ Visual customization (block type, glow, particles, holograms)
• ✅ Safe location algorithm (void/lava handling, search radius)
• ✅ Inventory handling (XP percentage, soulbound, overflow)
• ✅ Economy costs (teleport, retrieval, refunds)
• ✅ Guardian system (spawn chance, mob type, stats)
• ✅ Interaction modes (left/right/shift click behaviors)
• ✅ Respawn settings (compass, titles, messages)
• ✅ Cleanup automation (expired graves, database purging)
• ✅ GUI customization (titles, items, lore)
• ✅ Integration toggles (WorldGuard, Vault, PlaceholderAPI)
• ✅ Per-world settings (blacklist, behavior overrides)
• ✅ Debug options (logging, performance monitoring)

Every Feature is Configurable:

 Example: Disable a feature completely
guardian:
  enabled: false

 Example: Change behavior
inventory:
  overflow:
    mode: "DROP_AT_FEET"  Instead of leaving in grave

 Example: Customize visuals
visuals:
  block-material: "ENDER_CHEST"
  particles:
    type: "FLAME"
    count: 10

---

💬 Message Customization

350+ Message Lines including:

• ✅ All player-facing text
• ✅ MiniMessage format (gradients, RGB, hex colors)
• ✅ Placeholders (%player%, %x%, %cost%, etc.)
• ✅ Chat, title, actionbar, and hologram messages
• ✅ GUI item names and lore
• ✅ Error messages
• ✅ Debug messages

Example Customization:

 Default:
grave-spawned:
  chat: "%prefix%<yellow>Your grave has been created..."

 Custom (with gradient):
grave-spawned:
  chat: "%prefix%<gradient:red:gold>💀 RIP! Your items are safe at %x%, %y%, %z%</gradient>"

---

🏆 Why Choose UltimateGraves?

For Server Owners: ✅ Player retention - No rage-quits from item loss
✅ Flexible - Adapts to any server type
✅ Professional - Enterprise-grade code quality
✅ Performant - Async operations, optimized database
✅ Modern - Uses latest Minecraft features
✅ Supported - Regular updates for new MC versions

For Players: ✅ Fair - Items protected from unfair deaths
✅ Intuitive - Easy-to-use GUI and compass
✅ Visual - Clear markers and holograms
✅ Convenient - Teleport to graves (optional)
✅ Transparent - Know exactly when graves expire

📈 Performance Metrics

• Death Event Lag: < 1ms (async processing)
• Database Query Time: < 10ms (HikariCP pooling)
• Memory Usage: ~15MB for 500 cached graves
• Hologram Update Cost: < 0.1ms per grave per second
• Particle Spawn Cost: < 0.05ms per grave per tick

---

🛠️ Technical Architecture

Design Patterns Used:

• Strategy Pattern - Protection modes
• Repository Pattern - Database abstraction
• Factory Pattern - Grave creation
• Observer Pattern - Event system
• Singleton Pattern - Manager classes

Code Quality:

• ✅ SOLID principles
• ✅ DRY (Don't Repeat Yourself)
• ✅ Null-safety with annotations
• ✅ Exception handling
• ✅ Thread-safe operations
• ✅ JavaDoc documentation

---

📚 Documentation & Support

• 💬 Discord: geturplugins

---

🎉 Summary

UltimateGraves is the most comprehensive, customizable, and modern grave plugin available for Minecraft 1.21.1+. With 51 classes, 580+ config options, 350+ messages, and 5 protection modes, it's built for servers that demand quality.

Whether you need basic item protection or a complex economy-driven grave system with guardian mobs and token access, UltimateGraves delivers.

No bloat. No dependencies. Just pure, optimized grave management.

---

📥 Get Started

1. Download the latest release
2. Drop in plugins/ folder
3. Configure to your liking
4. Enjoy premium grave protection!

Version: 1.0.0
Author: geturplugins
Support: Discord (geturplugins)

---

Built with ❤️ using Paper API, Java 21, and modern Minecraft development practices.**