SoulKeeper

<div align="center"> # 👻 SoulKeeper ### Your items survive death. So does your progress. SoulKeeper captures your full inventory and experience into a **glowing soul** the instant you die — persisting through lava, fire, and even the void — and waits quietly at the death spot until you return to claim it. !(https://raw.githubusercontent.com/Astra-Interactive/SoulKeeper/refs/heads/master/media/souls.png) </div> --- ## ✨ Inspiration SoulKeeper is the spiritual successor of (https://github.com/Astra-Interactive/DeadSoulsKT) — rebuilt from scratch with a clean multiplatform architecture, async-first design, and a strong focus on reliability. Where DeadSoulsKT laid the foundation, SoulKeeper brings production-grade persistence, rich visual feedback, and cross-platform support to the same beloved mechanic. --- ## 💀 How Souls Work ### Creating a soul The moment you die, SoulKeeper silently intercepts the death event before anything hits the ground. Your **entire inventory** and a configurable portion of your **dropped XP** are captured and stored in the database as a soul — nothing is scattered across the floor. A burst of red particles and a resonant bell signal that your soul has been born. The soul appears as a shimmering particle cloud with a floating nameplate — **"Soul of \<Your Name\>"** — right where you fell. > Souls spawned in The End are clamped to a minimum Y so they can never sink into the void. ### Picking up a soul Just **walk close** — no right-click, no shift, no interaction. As soon as you enter the soul's range, it detects you and begins transferring: | Signal | Meaning | |-----------------------------------|-------------------------------------| | 🔵 Cyan dust particles | Soul holds XP | | ⚪ White dust particles | Soul holds items | | 🔔 Beacon ambient sound | Soul is nearby — follow the sound | | 🟣 Purple smoke + anvil sound | Inventory full — items still remain | | ✨ Bright flash + extinguish sound | Soul fully collected and gone | Items flow back inventory-slot by inventory-slot. If your inventory is full, **partial pickup** works: XP is absorbed, whatever fits goes in, and the soul persists with only what remains — no items are ever dropped or lost because of a full bag. ### Soul lifecycle ``` Death → ──── soul_free_after ────▶ ──── soul_fade_after ────▶ │ │ Only owner Any player can collect can collect ``` | State | Who can collect | Default timing | |----------------|-----------------|--------------------------------------------| | 🔒 **Private** | Owner only | Immediately after death | | 🔓 **Public** | Any player | After `soul_free_after` (default: 2 days) | | 💨 **Gone** | — | After `soul_fade_after` (default: 14 days) | Background workers (`FreeSoulWorker`, `DeleteSoulWorker`) run on a configurable tick cadence and advance souls through this lifecycle automatically — no cron jobs, no restarts, no admin action needed. --- ## 🗃️ Krates — Backup Storage Every death also writes a **Krate**: a standalone YAML snapshot of the soul, saved to disk **independently of the database**. ``` plugins/SoulKeeper/ deaths/ <player-uuid>/ <epoch-second>_0.yml ← first krate <epoch-second>_1.yml ← second krate (if retry occurred) ... ``` Krates are a last-resort safety net. Even if the SQLite database is lost, corrupted, or rolled back, an admin can restore any dead player's exact inventory from the krate file — **zero database interaction required**. ``` /soulkrate <uuid> <epoch-second> <index> ``` This reads the matching `<epoch>_<index>.yml` krate file and deposits its items directly into the requesting player's inventory. Use it when: - A database failure occurred during a busy session - A player was rolled back by an external tool - Items need to be restored from a specific past death --- ## 🚀 Features ### 🔄 Fully non-blocking Every heavy operation — soul creation, pickup detection, database reads/writes, background worker loops — runs on **Kotlin coroutines** dispatched to background threads via `KotlinDispatchers`. The main game thread is never touched for I/O. ### 🛡️ Safe, explicit failure paths Database operations return `kotlin.Result<T>`. Failures are logged at the call site and skipped gracefully — they never crash the server, silently eat items, or leave souls in a broken state. Concurrent DB writes in `SoulsDaoImpl`, the pickup loop in `PickUpWorker`, and death event handling in `ForgeSoulEvents`/`BukkitSoulEvents` are each guarded by their own `Mutex`. ### 📦 Krate safety net A file-based snapshot is written on every death independently