SafeChest

📦 SafeChest v0.0.5 — The Ultimate Player Safety & Server Management System

Tired of losing everything when you die? SafeChest automatically saves your entire inventory, armor, and off-hand item into a chest at your death location. Recover it easily — no more rage-quitting after falling into lava!

Version 0.0.5 is a REVOLUTION. We’ve added professional admin tools, sound effects, animated holograms, PlaceholderAPI integration, pagination, live GUI updates, and fixed critical performance bugs. This isn’t just a Death Chest plugin — it’s the ultimate safety net and server management suite for your players and staff.

✨ Key Features — v0.0.5 Edition

🛡️ Auto-Protection & Anti-Griefing
Only you (or admins) can open or break your chest. Configurable protection from entity/block explosions. Breaking your own chest now instantly restores your inventory — no more misclicks!

⏳ Live Multi-Line Animated Hologram Timer
Floating display shows your name, item count, and real-time countdown. Survives server restarts.
✨ NEW: Holograms now blink in red/yellow when time is running out (configurable threshold and colors).
✨ NEW: Option to blink only the {time} placeholder for subtle, elegant alerts.

🧭 /sctp — Teleport to Chest (Index Support)
One click, and you’re back at your death spot. Use /sctp 2 to teleport to a specific chest from your list. Configurable "force teleport" if no safe spot is found.
🔊 NEW: Play a configurable sound on teleport.

🧲 /scfetch — Bring Chest to You
Perfect for deaths in the void, lava, or caves. The chest (and its hologram) move with you.
🔊 NEW: Play a configurable sound on fetch.

👁️ /scpreview — Live Peek Inside (Auto-Refresh & Close Button)
View chest contents without moving — safe and read-only. Fully customizable GUI.
✨ NEW: GUI auto-refreshes every 5 seconds from the database. If the chest expires while you’re viewing it, the GUI closes automatically.
✨ NEW: Dedicated BARRIER close button in slot 44 for explicit closure.

📋 /sclist — All Active Chests (With Pagination!)
Clickable list of all your chests. Teleport to any instantly. Sort by time, filter by world, show UUIDs.
✨ NEW: Results are now paginated (5 per page) with clickable [Previous] and [Next] buttons. Use /sclist 3 to jump to page 3.

💰 Vault Economy Support (With Logging)
Charge players for /sctp or /scfetch — configurable per group. Action Bar feedback on payment.
📝 NEW: All payments and chest interactions are now logged to the server console for auditing and debugging.

👥 Group-Based Configuration (With Custom Chest Materials!)
Define custom rules for default, vip, admin — different durations, limits, prices, and even chest materials (e.g., VIPs get Barrels, Admins get Shulker Boxes).

💡 Players are assigned to the first group they have permission for.

💬 Interactive Death Messages (With Dynamic Cost & Time)
After dying, get clickable buttons: [TP], [FETCH], [PREVIEW]. Fully configurable per button.
✨ NEW: Hover text for buttons now shows dynamic placeholders like {cost} and {time}. Example: "Cost: 50 coins. Expires in: 2m 30s."

💾 Persistence & Auto-Restoration
Supports SQLite or MySQL storage. Chests and holograms are restored on server start.
⚠️ IMPORTANT: Table name changed from angelchests to safechests — manual migration required on update.

⚙️ Ultra-Configurable
Control everything: particle types, action bar messages, GUI titles, button visibility, world restrictions, explosion protection, sounds, hologram animations, and much more — all editable in config.yml.

🔄 /safechestreload
Reload configs without restarting the server — essential for live admins. Safer than /reload.

🎨 Visual & Audio Feedback
❤️ Configurable particles on creation. ✨ Configurable particles on recovery. Optional Action Bar messages.
🔊 NEW: Configurable sounds on creation, restore, teleport, and expiration.

🌐 Multi-World Support
Enable or disable the plugin in specific worlds. Filter /sclist to show only the current world.
✨ IMPROVED: Configuration now uses behavior.disabled-worlds (a blacklist) for clearer logic.

🧠 PlaceholderAPI Integration
✨ BRAND NEW: Use placeholders like %safechest_time_left%, %safechest_item_count%, %safechest_location% in any plugin that supports PlaceholderAPI (scoreboards, chat, menus, etc.).

🛠️ Admin Command Suite (/safechestadmin)
✨ BRAND NEW: A powerful toolkit for server staff:

• inspect <player>: List all active chests for a player (click to teleport).
• delete <uuid>: Delete a specific chest by its UUID.
• purge: Manually purge all expired chests from the database.
• stats: Show server-wide statistics (total active/expired chests, players with chests, etc.).

⚠️ Critical Bug Fixes:

• 🐞 Fixed: Deadlock on Chest Interaction/Breaking — No more server freezes when clicking or breaking chests. Operations are now fully asynchronous.
• 🐞 Fixed: Hologram Timer Inactive on Restart — Holograms now start their countdown timer correctly after a server reboot.
• 🐞 Fixed: Economy Errors Not Logged — Payment failures are now logged to the server console for easy debugging.

📘 Wiki: How to Use SafeChest v0.0.5

🧭 1. Basic Usage (For Players)

💀 When You Die

• A chest will automatically appear at your death location.
• All your items (inventory, armor, off-hand) are stored inside.
• You’ll receive a configurable chat message with clickable buttons:
  • [TP] → /sctp — Teleports you to the chest. Hover shows cost and time remaining.
  • [FETCH] → /scfetch — Brings the chest to you. Hover shows cost and time remaining.
  • [PREVIEW] → /scpreview — Shows chest contents without moving. Hover shows time remaining.

📥 To Recover Your Items

• Walk to the chest and right-click it to restore your inventory.
• Or use /sctp to teleport to it.
• Or use /scfetch to bring it to you.

👀 Preview Your Chest (No Movement Needed)

/scpreview

• Opens a virtual inventory showing all your stored items.
• Completely safe — you can’t take or modify anything.
• The GUI updates live every 5 seconds. If the chest expires, the GUI closes automatically.
• Click the red BARRIER in the bottom row to close it manually.

📋 List All Your Active Chests (Paginated!)

/sclist

• Shows all your active chests in pages of 5.
• Configurable: Filter by current world, sort by expiration time, show UUID in hover.
• Click any entry to teleport directly to that chest (if you have permission).
• Use /sclist 2 to jump to page 2.

⚙️ 2. Configuration (For Server Admins)

📁 Files You Can Customize

• config.yml — Main settings: storage, chest material, hologram text, particle types, death message buttons, GUI options, world restrictions, explosion protection, sounds, hologram animations, logging, and much more.
• groups.yml — Define player groups (e.g., default, vip, admin) with custom durations, chest limits, command prices, and chest materials.
• lang.yml — Translate or customize every message in the plugin, including new messages for pagination, admin commands, and logging.

🎯 Example: Creating a VIP Group

In groups.yml:

vip:
  safechest-duration: 600      # 10 minutes
  max-allowed-safechests: 10   # Can have up to 10 active chests
  price-teleport: 50.0         # Costs 50 coins to teleport
  price-fetch: 100.0           # Costs 100 coins to fetch
  material: "BARREL"           # ✅ NEW: VIPs get Barrels instead of Chests!

Then, give players the permission:
safechest.group.vip

💡 Players are assigned to the first group they have permission for.

🖋️ Customizing the Hologram & Death Message

In config.yml:

angelchest:
  hologram-text: "&a&l[SafeChest]&r\n&b{player}\n&7{items} items / {time}"

# ✅ NEW SECTION: HOLOGRAM ANIMATION
hologram-animation:
  enabled: true
  threshold-seconds: 10 # Start blinking when 10 seconds or less remain
  color-on: "RED"
  color-off: "YELLOW"
  blink-only-time-placeholder: true # Only blink the {time} part

death-message:
  enabled: true
  show-buttons: true
  show-button-tp: true
  show-button-fetch: false # Disable fetch globally
  show-button-preview: true

Placeholders (for hologram-text, lang.yml, and death message hovers):

• {player} — Player’s name.
• {items} — Total number of items in the chest.
• {time} — Time remaining until expiration.
• {cost} — Cost of the action (for death message hovers).

✅ Multi-line holograms are now fully supported and restored on server restart.

🎮 Customizing the Player Experience

In config.yml:

messages:
  use-action-bar: true # Show "Chest Created!" in action bar instead of chat
  use-particles: true
  particle-on-create: "HEART"
  particle-on-restore: "END_ROD"

# ✅ NEW SECTION: SOUNDS
sounds:
  enabled: true
  on-create: "ENTITY_PLAYER_LEVELUP"
  on-restore: "ENTITY_ENDERMAN_TELEPORT"
  on-teleport: "ENTITY_ENDERMAN_TELEPORT"
  on-expire: "ENTITY_ITEM_BREAK"

commands:
  preview-gui:
    title: "&6My Items - SafeChest" # Change the GUI title
    info-item-material: "BOOK" # Change the info item
    force-close-only-with-esc: true # Only close preview with ESC key

  aclist:
    show-only-current-world: true # Only show chests in the player's current world
    sort-by-expiration: true # Show expiring chests first
    show-uuid-in-hover: false # Hide UUID (useful for debugging if true)

🛡️ Advanced Behavior Control

In config.yml:

behavior:
  # ✅ RENAMED: From 'enabled-worlds' to 'disabled-worlds'
  disabled-worlds: ["world_the_end"] # Disable plugin in The End
  protect-from-entity-explosions: true # Protect from Creepers
  protect-from-block-explosions: false # Allow TNT to destroy chests
  force-clear-drops-on-death: true # Fix double-drop bug

💰 3. Economy Setup

SafeChest integrates with Vault. Make sure you have a compatible economy plugin installed (e.g., EssentialsX, CMI).

💵 Charging for Commands

In groups.yml or config.yml, set prices:

price-teleport: 50.0
price-fetch: 100.0

Players will be charged automatically when using /sctp or /scfetch.

✅ If Vault is not installed, these features are silently disabled — no errors. (softdepend: [Vault]).

🔄 4. Reloading Configurations

As an admin, you can reload all configurations without restarting the server:

/safechestreload

Required Permission: safechest.reload

This command:

• Reloads config.yml, groups.yml, and lang.yml.
• Clears expired chests from cache.
• Reinitializes the plugin container.
• Does NOT break active chests or holograms.

🚫 Warning: Avoid using /reload during heavy server activity. /safechestreload is much safer.

🛡️ 5. Permissions (Renamed!)

✅ Use LuckPerms, PermissionsEx, or any other permission manager to assign these.

❓ 6. FAQ & Troubleshooting — v0.0.5

Q: Why aren’t my items being saved?
A: Make sure you have permission safechest.use. Also, check if the world is NOT listed in behavior.disabled-worlds in config.yml.

Q: The hologram disappeared after a restart!
A: Fixed in v0.0.3 and perfected in v0.0.5! Holograms are now automatically restored and their timers are restarted on server start. If they’re still missing, check server logs for errors.

Q: I get “Initializing... try again later”.
A: The database is still loading. Wait a few seconds and try again.

Q: Can I change the chest to a Barrel or Shulker Box?
A: Yes! In config.yml, set globally:

material: "BARREL"

Or per-group in groups.yml:

vip:
  material: "SHULKER_BOX"

Q: How do I disable the death message buttons?
A: In config.yml, set death-message.show-buttons: false, or disable individual buttons like show-button-fetch: false.

Q: My players are complaining about double drops!
A: Enable behavior.force-clear-drops-on-death: true in config.yml to fix this.

Q: How do I make /sctp work even if there’s no “safe spot”?
A: Set commands.teleport-unsafe-behavior: "force" in config.yml.

Q: How do I upgrade from v0.0.4?
A: CRITICAL: You must rename your database table from angelchests to safechests before starting the server. Also, update all permissions and commands from angelchest to safechest.

Q: How do I see server stats?
A: Use the new admin command: /safechestadmin stats.

Q: How do I delete a specific chest?
A: Use /safechestadmin delete <uuid>. You can find the UUID via /safechestadmin inspect <player>.