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. 💰 Economy - Finds a safe spot (handles void, lava, walls) 2. 💰 Economy - All inventory, armor, and offhand items stored 3. 💰 Economy - Visual marker placed (player head, hologram, particles) 4. 💰 Economy - Configurable protection modes (private, public, timed, PvP, token-based) 5. 💰 Economy - Player receives compass pointing to grave 6. 💰 Economy - Configurable timer before grave becomes public/expires 7. 💰 Economy - Optional costs for teleportation and retrieval (Vault integration)

---

✨ Key Features Summary

| Category | Features | |----------|----------| | 🔌 Integration | 5 Protection Modes, Timed Access, PvP Detection, Token System, Guardian Mobs | | 🔌 Integration | Player Head Graves, Native Holograms, Particle Effects, Beacon Beams, Glow Effects | | 🔌 Integration | SQLite & MySQL Support, Async Operations, HikariCP Pooling, NBT Preservation | | 🔌 Integration | Safe Location Finder, Void/Lava Handling, Soulbound Items, Overflow Management | | 🔌 Integration | Vault Integration, Teleport Costs, Retrieval Fees, Item Refunds | | 🔌 Integration | Interactive GUI, Quick Loot, Smart Equip, Compass Tracking, Multi-Click Actions | | 🔌 Integration | 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)

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

Auto-updates (TextDisplay Entities - NO PLUGINS NEEDED): ``` ⚰ GRAVE ⚰ Owner: Steve Time: 14m 32s Cause: Fell into Lava Items: 47 ``` - Auto-updates - Auto-updates - Auto-updates (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: ```java 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. locked until guardian is killed 👻 - locked until guardian is killed (default 15%) - Zombie/Skeleton equipped with locked until guardian is killed - 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. stay in inventory on death 💍 - Mark items with lore/NBT tags - These items stay in inventory on death - Configurable identifiers: ```yaml - "<gold><bold>SOULBOUND</bold></gold>" - "§6§lSOULBOUND" - NBT tag: "soulbound:true" ``` - Perfect for quest items, rank rewards, etc.

3. PREVENT_LOOT 📦 - Player inventory full when looting grave? - PREVENT_LOOT - PREVENT_LOOT - Items stay for next visit - PREVENT_LOOT - 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

MySQL - MySQL - 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

attributes - attributes for items - attributes preserved (modded items, custom model data) - attributes and attributes retained - attributes 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 | |--------|--------| | Shift + Right Click | Show grave info in chat | | Shift + 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)

Retrieve items - Retrieve items - Default $100 - Retrieve items - Default $0 (disabled) - Retrieve items - Default $0 (disabled)

Detailed messages - Detailed messages - Convert expired grave items to money - Detailed messages - `ultimategraves.teleport.free`, `ultimategraves.nocost` - Detailed messages - 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

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

Config: ⚔️ - Config: Need lootable graves for kills, but not for accidents - Config: PVP_PVE mode - Config: Instant public graves for PvP, protected for PvE deaths

Config: 🗡️ - Config: Custom items need special protection - Config: Soulbound + Guardian system - Config: Mark quest items as soulbound, 50% guardian spawn chance

Config: 💀 - Config: Too easy if items always protected - Config: Short timer + guardian mobs - Config: `TIMED` 2 minutes, 30% guardian chance, no teleport

Config: 🔥 - Config: No rules, full loot - Config: Public graves, short expiration - Config: `PUBLIC` mode, 5-minute expiration, void protection only

Config: 🏘️ - Config: Mix of casual and hardcore players - Config: Permission-based modes - Config: Different modes per rank, optional teleport costs

---

📊 Comparison with Other Plugins

| Feature | UltimateGraves | Graves (Basic) | AngelsChest | GriefPrevention Graves | |---------|----------------|----------------|-------------|------------------------| | Configuration | ✅ Yes | ❌ No | ❌ No | ❌ No | | Configuration | ✅ TextDisplay | ❌ Armor Stands | ❌ External | ❌ None | | Configuration | ✅ SQLite + MySQL | ❌ File-based | ✅ SQLite | ❌ None | | Configuration | ✅ Full | ❌ Partial | ❌ No | ❌ No | | Configuration | ✅ 5 Modes | ❌ 2 Modes | ❌ 1 Mode | ❌ 1 Mode | | Configuration | ✅ Yes | ❌ No | ❌ No | ❌ No | | Configuration | ✅ Yes | ❌ No | ❌ No | ❌ No | | Configuration | ✅ Yes | ❌ No | ❌ No | ❌ No | | Configuration | ✅ Full | ❌ Partial | ❌ No | ❌ No | | Configuration | ✅ Yes | ❌ Limited | ❌ No | ❌ No | | Configuration | ✅ Advanced | ❌ Basic | ❌ None | ❌ None | | Configuration | ✅ 580+ lines | ❌ 100 lines | ❌ 150 lines | ❌ 50 lines |

---

🚀 Installation & Setup

Optional Dependencies: - Optional Dependencies: 1.21.1 - 1.21.x - Optional Dependencies: Paper (or Forks: Purpur, Pufferfish) - Optional Dependencies: 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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml ultimategraves.keepxp Keep 100% XP ultimategraves.soulbound.bypass All items act as soulbound ```

---

⚙️ Configuration Highlights

580+ Configuration Options including:

- ✅ Debug options (type, MySQL credentials, pool size) - ✅ Debug options (max per player, expiration time) - ✅ Debug options (5 types with sub-options) - ✅ Debug options (block type, glow, particles, holograms) - ✅ Debug options (void/lava handling, search radius) - ✅ Debug options (XP percentage, soulbound, overflow) - ✅ Debug options (teleport, retrieval, refunds) - ✅ Debug options (spawn chance, mob type, stats) - ✅ Debug options (left/right/shift click behaviors) - ✅ Debug options (compass, titles, messages) - ✅ Debug options (expired graves, database purging) - ✅ Debug options (titles, items, lore) - ✅ Debug options (WorldGuard, Vault, PlaceholderAPI) - ✅ Debug options (blacklist, behavior overrides) - ✅ Debug options (logging, performance monitoring)

Every Feature is Configurable: ```yaml 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 - ✅ Placeholders (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: ```yaml 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?

Supported ✅ Supported - No rage-quits from item loss ✅ Supported - Adapts to any server type ✅ Supported - Enterprise-grade code quality ✅ Supported - Async operations, optimized database ✅ Supported - Uses latest Minecraft features ✅ Supported - Regular updates for new MC versions

Transparent ✅ Transparent - Items protected from unfair deaths ✅ Transparent - Easy-to-use GUI and compass ✅ Transparent - Clear markers and holograms ✅ Transparent - Teleport to graves (optional) ✅ Transparent - Know exactly when graves expire ---

📈 Performance Metrics

- Particle Spawn Cost: < 1ms (async processing) - Particle Spawn Cost: < 10ms (HikariCP pooling) - Particle Spawn Cost: ~15MB for 500 cached graves - Particle Spawn Cost: < 0.1ms per grave per second - Particle Spawn Cost: < 0.05ms per grave per tick

---

🛠️ Technical Architecture

Singleton Pattern - Singleton Pattern - Protection modes - Singleton Pattern - Database abstraction - Singleton Pattern - Grave creation - Singleton 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

5 protection modes is the 5 protection modes grave plugin available for Minecraft 1.21.1+. With 5 protection modes, 5 protection modes, 5 protection modes, 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!

Support: 1.0.0 Support: geturplugins Support: Discord (geturplugins)

---

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