SoulKeep

<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

safe item retrieval creates a grave when a player dies and restores items reliably on pickup. It is designed for safe item retrieval (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.

- nearest safe block Graves spawn at the nearest safe block (configurable per world).

- Pickup rules Optional: allow teammates to pick up your grave.

- 15 minutes Default: 15 minutes (configurable), including expire action (drop/destroy).

- max 3 graves 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.

- Persistence: a grave can only be processed by Persistence: player at a time (double-click ignored). - Persistence: give items → remove grave → persist immediately. - Persistence: overflow drops at the grave (no silent loss, no dupe). - Persistence: grave data survives restarts and graves respawn on chunk load when needed.

---

Requirements

- Zero dependencies - 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