SoulKeeper

✨ Вдохновение

SoulKeeper — духовный наследник DeadSoulsKT, переписанный с нуля с чистой мультиплатформенной архитектурой, async-first дизайном и упором на надёжность. Там, где DeadSoulsKT заложил фундамент, SoulKeeper приносит продакшн-надёжность, богатую визуальную отдачу и кроссплатформенную поддержку той же любимой механики.

💀 Как работают души

Создание души

В момент твоей смерти SoulKeeper тихо перехватывает событие смерти до того, как что-либо упадёт на землю. Твой весь инвентарь и настраиваемая часть выпавшего XP сохраняются в базе данных как душа — ничего не разбрасывается по полу.

Вспышка красных частиц и звонкий колокол возвещают о рождении твоей души. Душа появляется как мерцающее облако частиц с парящей табличкой — "Soul of <Твоё Имя>" — прямо там, где ты упал.

Души, появившиеся в The End, ограничены минимальным Y, чтобы они никогда не утонули в пустоте.

Подбор души

Просто подойди близко — без правого клика, без шифта, без взаимодействия. Как только ты входишь в радиус души, она замечает тебя и начинает передачу:

Предметы возвращаются слот за слотом. Если инвентарь полон, работает частичный подбор: XP поглощается, что влезает — входит, а душа остаётся только с тем, что не поместилось — предметы никогда не выпадают и не теряются из-за полной сумки.

Жизненный цикл души

Смерть → [PRIVATE] ──── soul_free_after ────▶ [PUBLIC] ──── soul_fade_after ────▶ [DELETED]
           │                                      │
      Только владелец                      Любой игрок
      может забрать                        может забрать

Фоновые воркеры (FreeSoulWorker, DeleteSoulWorker) работают с настраиваемой частотой тиков и автоматически продвигают души по этому жизненному циклу — без cron-задач, без перезапусков, без действий администратора.

🗃️ Krates — резервное хранилище

Каждая смерть также записывает Krate: отдельный YAML-снимок души, сохранённый на диск независимо от базы данных.

plugins/SoulKeeper/
  deaths/
    <player-uuid>/
      <epoch-second>_0.yml   ← первый krate
      <epoch-second>_1.yml   ← второй krate (если была повторная попытка)
      ...

Krates — это страховочная сеть на крайний случай. Даже если база данных SQLite потеряна, повреждена или откатана, админ может восстановить точный инвентарь любого погибшего игрока из krate-файла — **без единого обращения к базе данных**.

/soulkrate

Команда читает соответствующий krate-файл `<epoch>_<index>.yml` и кладёт его предметы прямо в инвентарь запрашивающего игрока. Используй её, когда:

- Во время оживлённой сессии произошёл сбой базы данных
- Игрока откатил сторонний инструмент
- Предметы нужно восстановить с конкретной прошлой смерти

---

## 🚀 Возможности

### 🔄 Полностью неблокирующий

Каждая тяжёлая операция — создание души, определение подбора, чтение/запись в базу данных, фоновые циклы воркеров — выполняется на **корутинах Kotlin**, отправленных в фоновые потоки через `KotlinDispatchers`. Главный поток игры никогда не трогается для I/O.

### 🛡️ Безопасные, явные пути отказа

Операции с базой данных возвращают `kotlin.Result<T>`. Ошибки логируются в месте вызова и аккуратно пропускаются — они никогда не роняют сервер, не съедают предметы молча и не оставляют души в сломанном состоянии. Конкурентные записи в БД в `SoulsDaoImpl`, цикл подбора в `PickUpWorker` и обработка событий смерти в `ForgeSoulEvents`/`BukkitSoulEvents` — каждый защищён собственным `Mutex`.

### 📦 Страховочная сеть Krate

Файловый снимок записывается при каждой смерти независимо от базы данных. Предметы не могут быть потеряны при катастрофическом сбое БД.

### 🎨 Полностью настраиваемые эффекты

Каждая частица (тип, цвет, размер, количество) и каждый звук (ID, громкость, высота тона) настраиваются независимо для каждого типа события. Шесть звуковых сигналов, пять эффектов частиц — всё настраивается без правки кода.

### ⏳ Настраиваемый жизненный цикл души

`soul_free_after` и `soul_fade_after` — обычные значения длительности. Задавай их в секундах, минутах, часах или днях. Фоновые сервисы опрашивают реактивно из конфига `Flow` — изменения подхватываются на лету без перезапуска.

### 📈 Частичный подбор

Если твой инвентарь полон, когда ты доходишь до души, сначала собирается XP, затем влезает столько предметов, сколько помещается. Душа остаётся с остатком. Вернись, когда появится место — ничего никогда не выбрасывается принудительно.

### 🏷️ Виртуальные парящие таблички с именами

Парящие таблички на стойках для брони («Soul of \<Player\>») отправляются как **виртуальные сущности через PacketEvents** на Bukkit — в мир не спавнится ни одной реальной сущности, так что производительность не страдает независимо от количества душ.

### 🔔 Зов души поблизости

`SoulCallWorker` отслеживает позицию каждого игрока в сети. Когда игрок входит в `soul_call_radius` блоков от души, которую может собрать, начинают пульсировать звуки и частицы — они ведут его обратно даже в полной темноте или глубоко под землёй.

### 🌍 Безопасность в измерении Энда

Души, заспавненные в The End, ограничиваются по `endLocationLimitY`, чтобы они никогда не падали ниже дна острова и не становились недосягаемыми.

### 📑 Постраничный браузер душ

`/souls` перечисляет все видимые души с именем владельца, координатами, возрастом (в формате «X days ago») и индикаторами предметов/XP. Админы видят кликабельные кнопки **[FREE]** и **[TP]** прямо в строке. 5 душ на страницу; навигация вперёд/назад включена.

### 🗄️ Версионированные миграции базы данных

`DatabaseMigrator` содержит все шаги миграции схемы. Обновление плагина никогда не требует ручного SQL — миграции выполняются автоматически при запуске.

---

## ⚙️ Конфигурация

Все настройки находятся в `config.yml` в папке данных плагина и перезагружаются на лету через `/skreload`.

```yaml
# Путь к файлу базы данных (SQLite)
database: ...

# Душа становится публично доступной для сбора через этот промежуток времени
soul_free_after: 2d

# Душа исчезает навсегда через этот промежуток времени
soul_fade_after: 14d

# Радиус (в блоках), в пределах которого душа издаёт звуки/частицы, чтобы вести владельца
soul_call_radius: 100

# Доля выпавшего XP, сохраняемая в душе (0.0 – 1.0)
retained_xp: 1.0

# Минимальный Y для душ в The End (предотвращает потерю в пустоте)
end_location_limit_y: 0.0

# Показывать парящие таблички «Soul of <player>» над душами
display_soul_titles: true

# Как обрабатываются смерти в PvP
# NONE        – смерти в PvP не создают душу
# EXP_ONLY    – душа хранит только XP
# ITEMS_ONLY  – душа хранит только предметы
# EXP_AND_ITEMS – душа хранит всё (как при обычной смерти)
pvp_behaviour: NONE

### 🎵 Звуки

Каждый звуковой сигнал настраивается отдельно с помощью `id`, `volume` и `pitch`:

| Ключ                | Звук по умолчанию                | Триггер                      |
|---------------------|----------------------------------|------------------------------|
| `collect_xp`        | `entity.experience_orb.pickup`   | Опыт поглощён из души        |
| `collect_item`      | `item.trident.return`            | Предметы поглощены из души   |
| `soul_disappear`    | `entity.generic.extinguish_fire` | Душа полностью собрана       |
| `soul_dropped`      | `block.bell.resonate`            | Душа создана при смерти      |
| `soul_calling`      | `block.beacon.ambient`           | Душа пульсирует рядом с владельцем |
| `soul_content_left` | `block.anvil.place`              | Инвентарь полон, предметы остались |

### 🌟 Частицы

Каждый эффект частиц настраивается отдельно с помощью `key`, `count` и опционального `dust_options` (цвет RGBA + размер):

| Ключ                | Цвет по умолчанию | Триггер                          |
|---------------------|-------------------|----------------------------------|
| `soul_items`        | Белый `#FFFFFF`   | Душа содержит предметы (постоянно) |
| `soul_xp`           | Голубой `#00FFFF` | Душа содержит опыт (постоянно)   |
| `soul_created`      | Красный `#eb3437` | Вспышка при создании души        |
| `soul_gone`         | Жёлтый `#FFFF00`  | Вспышка при полном сборе         |
| `soul_content_left` | Фиолетовый `#a103fc` | Предупреждение о полном инвентаре |

---

## 🛠️ Команды

| Команда                             | Описание                           | Право                 |
|-------------------------------------|------------------------------------|-----------------------|
| `/skreload`                         | Горячая перезагрузка конфига и переводов | `soulkeeper.reload`   |
| `/souls [page]`                     | Список ваших душ (5 на страницу)   | *(нет)*               |
| `/souls [page]`                     | Список **всех** душ на сервере     | `soulkeeper.all`      |
| `/souls` → **\[FREE\]**             | Мгновенно освободить любую душу    | `soulkeeper.free.all` |
| `/souls` → **\[TP\]**               | Телепорт к местоположению души     | `soulkeeper.teleport` |
| `/soulkrate <uuid> <epoch> <index>` | Восстановить предметы из krate-файла | `soulkeeper.load`     |

---

## 🌐 Мультиплатформенность

SoulKeeper поставляется в виде **отдельного fat-jar** для каждой поддерживаемой платформы. Вся основная логика — жизненный цикл души, определение подбора, база данных, фоновые воркеры, команды — живёт в общих платформо-независимых модулях. Только привязка событий и сериализация предметов зависят от платформы.

| Платформа          | Jar                       | Минимальная версия |
|--------------------|---------------------------|--------------------|
| **Paper / Spigot** | `soulkeeper-bukkit.jar`   | Paper 1.21.1       |
| **Forge**          | `soulkeeper-forge.jar`    | Forge 1.21.1       |
| **NeoForge**       | `soulkeeper-neoforge.jar` | NeoForge 1.21.1    |

Выберите jar для своей платформы и просто закиньте его — те же данные душ, те же команды, то же поведение везде.

---

## 🎬 Превью

### При смерти — душа создана

https://github.com/user-attachments/assets/ec5f1437-0dab-404f-a4a8-725ee1cd9129

### При возврате — душа собрана

https://github.com/user-attachments/assets/75f58f92-7d13-4c23-a7fb-b2d89476748b

---

## ⚠️ Известные несовместимости

- Плагины, которые **отменяют или сильно изменяют `PlayerDeathEvent`** (Bukkit) или аналогичные события выпадения (Forge/NeoForge), могут помешать созданию души. Предметы могут захватываться некорректно при наличии таких плагинов.

---

## 🐛 Поддержка

1. Воспроизведи проблему в чистой среде (без посторонних плагинов/модов).
2. Собери полный лог сервера от запуска до момента возникновения проблемы.
3. [Зайди на наш Discord](https://discord.com/invite/8fEzV2TDS2) и открой тикет в `#support`.

## 💡 Предложения по функционалу

Открой тикет в `#suggestions` в нашем [Discord](https://discord.com/invite/8fEzV2TDS2), и мы обсудим его, прежде чем создавать issue на GitHub.

---

<div align="center">

Больше плагинов от [AstraInteractive](https://github.com/Astra-Interactive)
</div>