DeathLog - Death History & Item Recovery

Lightweight death history and item recovery plugin for Paper/Spigot servers with SQL database storage.

DeathLog is a lightweight admin plugin for Paper/Spigot that stores player death history directly in a database, displays lost items through a convenient GUI, and allows staff to safely restore lost items.

Instead of constantly reading and rewriting large YAML files, each death is stored as an individual database record. This provides better performance, faster death history access, and makes DeathLog suitable for servers with large amounts of death history.

🗄️ Database Storage

DeathLog supports:

• SQLite — default
• MySQL
• MariaDB
• PostgreSQL

Database operations use a connection pool and are executed asynchronously, keeping SQL queries away from the Minecraft main thread.

Existing YAML death data can be automatically migrated to the database on the first launch. Original YAML files are backed up and are not automatically deleted.

---

---

✨ Features

• SQL database storage

• SQLite, MySQL, MariaDB and PostgreSQL support

• Asynchronous database operations

• Connection pooling with HikariCP

• SQL pagination for death history

• Automatic YAML → SQL migration

• Automatic migration backup

• Logs player deaths using PlayerDeathEvent

• Death history GUI

• View lost items for each death

• Full ItemStack saving:

  • meta
  • NBT
  • enchantments
  • lore
  • custom item data

• Saves:

  • world
  • coordinates
  • death time
  • yaw/pitch

• Detects:

  • death cause
  • killer
  • player / mob / projectile

• Teleport staff to death locations

• Restore items directly through GUI

• Inventory free-space check before restore

• One-time restore protection

• Logs the administrator who restored items

• Removes tracked world drops after restore

• Removes items from players who picked up someone else's death loot

• Removes equipped stolen items from:

  • armor slots
  • offhand

• Removes placed blocks created from death loot

• Attempts block rollback at death location

• Configurable death limit per player with FIFO cleanup

• Player opt-out system for death saving

• Pending restore support

• EN/RU language support

• Configurable prefix and core settings

---

📜 Commands

/deathlog

Open your death history.

/deathlog <player>

Open another player's death history.

/deathlog clear

Clear your death history.

/deathlog clear <player>

Clear another player's death history.

/deathlog nosave <deathId>

Used by the opt-out button to remove a saved death.

---

🔑 Permissions

By default, only OP has access.

deathlog.view

Access your own history.

deathlog.others

View and manage other players' histories.

deathlog.restore

Restore items.

---

♻️ Restore

Before Restore

• Player must be online when required by configuration
• Free inventory space is checked
• Death must not already be restored
• Death data is loaded directly from the database

After Restore

• Items are returned to the dead player
• Armor is restored to armor slots if available
• Offhand items are restored to the offhand slot if free
• Inventory items return to original slots if available
• Occupied slots fallback to free inventory space
• Tracked drops are removed from the world
• Picked-up items are removed from other players
• Equipped stolen items are removed from:

• inventory
• armor
• offhand
• Blocks placed from death loot are removed
• Restore administrator is logged

If a restore operation fails, the death record is not removed, preventing accidental data loss.

---

💀 Death Saving

After death, the player receives a chat message:

Death info saved for staff. [Do not save]

Behavior

• If the player does nothing:

  • the death remains saved for staff

• If the player clicks:

[Do not save]

the death record is deleted from the database and hidden from staff.

---

⚙️ Config

File:

plugins/DeathLog/config.yml

language: "en"
prefix: "&8[&cDeathLog&8] &7"

database:
  type: SQLITE
  host: localhost
  port: 3306
  database: deathlog
  username: root
  password: ""
  ssl: false
  file: deaths.db
  pool-size: 10

storage:
  max_deaths_per_player: 10
  date_format: "dd.MM.yyyy HH:mm:ss"
  auto_save_on_death: true
  allow_player_opt_out: true

restore:
  require_player_online: true
  check_inventory_space: true
  one_time_restore: true
  remove_world_drops: true
  remove_picked_items: true
  remove_picked_items_on_join: true
  remove_placed_blocks: true
  block_rollback: true
  notify_target: true

tracking:
  dropped_item_search_radius: 4.0
  track_picked_items: true
  track_placed_blocks: true

gui:
  history_size: 54
  details_size: 54
  teleport_slot: 45
  restore_slot: 49
  back_slot: 53

---

🗄️ Database

DeathLog creates the following main tables:

players

Stores player information:

• internal ID
• UUID
• username
• first seen
• last seen

deaths

Stores individual death records:

• death ID
• player ID
• death time
• world
• coordinates
• death cause
• killer information
• experience
• inventory
• armor
• offhand
• original slots
• rollback data
• tracked drops
• picked items
• placed blocks
• restore status
• pending restore data

Indexes are used for player UUIDs, player death history, death time, and (player_id, death_time) queries.

Death history is loaded using SQL pagination instead of loading the entire database into memory.

---

🔄 YAML Migration

If DeathLog detects an existing YAML death file, it automatically migrates the data to SQL.

The migration:

• Creates the database tables
• Imports existing deaths
• Preserves all supported death data
• Checks the number of imported records
• Prevents duplicate imports
• Stores the migration version
• Creates a backup of the original YAML
• Does not automatically delete the old YAML

This allows existing servers to upgrade without manually converting their death history.

---

🌍 Languages

Default language:

English

Available Languages

en — English
ru — Русский

Language Files

plugins/DeathLog/lang/en.yml
plugins/DeathLog/lang/ru.yml

Russian Language

language: "ru"

After changing the language, restart the server.

---

📦 Installation

1. Download

DeathLog.jar

2. Move

Place the jar into:

plugins/

3. Restart

Start or restart your server.

4. Configure

Edit:

plugins/DeathLog/config.yml

Choose your database type and configure the connection if you are using MySQL, MariaDB, or PostgreSQL.

---

🧩 Compatibility

Minecraft: 1.20+ / 1.21+
Platform: Paper / Spigot
Java: 17+

DeathLog does not require Java 21+ or Paper-only APIs.

---

🎯 Use Cases

DeathLog is useful for:

• Survival servers
• Grief-control systems
• Staff utility servers
• Hardcore gameplay
• Administrative moderation
• Large servers with extensive death histories
• Any server where staff need fast and safe item recovery tools

---

❤️ DeathLog

Simple. Safe. Fast. Database-powered death recovery.