<p align="center"> <img src="https://img.shields.io/badge/Minecraft-1.21+-62b47a?style=for-the-badge&logo=minecraft" alt="Minecraft 1.21+"/> <img src="https://img.shields.io/badge/Paper-API-FF5555?style=for-the-badge" alt="Paper API"/> <img src="https://img.shields.io/badge/Zero-Dependencies-7289da?style=for-the-badge" alt="Zero Dependencies"/> </p> <h1 align="center">SoulKeep</h1> <p align="center"><strong>Persistent graves for Paper 1.21+</strong></p> <p align="center">Graves, auto grave compass, lava/void-safe placement — no database, no dependencies.</p> --- ## Overview **SoulKeep** creates a grave when a player dies and restores items reliably on pickup. It is designed for **persistence** (restarts / chunk reloads) and **safe item retrieval**. --- ## Features - **Graves at death location** Player head + hologram at (or near) the death spot. - **Grave Compass (on respawn)** Optional compass that points to the grave. Removed after successful pickup. - **Lava/Void-safe placement** Graves spawn at the **nearest safe block** (configurable per world). - **Pickup rules** Optional: allow teammates to pick up your grave. - **Auto-expire** Default: **15 minutes** (configurable), including expire action (drop/destroy). - **Per-player limits** Default: **max 3 graves**. When exceeded, the oldest grave is handled by the configured rule. - **Slot-aware restoration** Inventory/Hotbar/Armor/Offhand are restored with priority and, when possible, returned to their original slots. --- ## Dupe-resistant design > **Important:** SoulKeep reduces dupe edge cases via locking and atomic retrieval. - **Locking:** a grave can only be processed by **one** player at a time (double-click ignored). - **Atomic retrieval:** give items → remove grave → persist immediately. - **Inventory full:** overflow drops at the grave (no silent loss, no dupe). - **Persistence:** grave data survives restarts and graves respawn on chunk load when needed. --- ## Requirements - **Paper 1.21+** - **Zero dependencies** (no Vault, no PlaceholderAPI, no external database) --- ## Installation 1. Put `SoulKeep-<version>.jar` into `plugins/` 2. Start the server 3. Optional: edit `plugins/SoulKeep/config.yml` 4. Run `/soulkeep reload` (or restart) after config changes --- ## Commands & Permissions | Command | Description | Permission | |--------|-------------|------------| | `/soulkeep` | Lists your active graves (with coordinates) | – | | `/soulkeep reload` | Reloads the config | `soulkeep.admin` | | `/soulkeep clean` (`/sk clean`) | Removes your graves and drops items; Admin/Console can clean globally | Admin: `soulkeep.admin` | | Permission | Default | Description | |-----------|---------|-------------| | `soulkeep.admin` | OP | Administrative functions (reload/clean/global) | | `soulkeep.lavavoidproof` | Everyone | Enables lava/void-safe placement (if permission-gated) | --- ## Configuration (excerpt) ```yaml # Lava/Void protection lava-void-proof: true lava-void-proof-worlds: {} # e.g. world_nether: false -> Overworld only # Grave Compass compass-tracking: true # Limits max-graves: 3 # Expiration grave-expire-hours: 0.25 # hours (0 = never) expire-action: DROP # DROP or DESTROY