SoulKeep

Persistent graves for Paper 1.21+

Graves, auto grave compass, lava/void-safe placement — no database, no dependencies.

---

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)

# 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