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!)

Permission	Description	Default
safechest.use	Allows using the Death Chest system	true
safechest.protect	Allows protecting your chest from others	true
safechest.protect.ignore	Allows opening SafeChests protected of other players	op
safechest.tp	Allows using /sctp	true
safechest.fetch	Allows using /scfetch	true
safechest.group.<name>	Assigns player to a group (e.g., safechest.group.vip)	—
safechest.reload	Allows using /safechestreload	op
safechest.admin	✅ NEW: Allows using /safechestadmin	op

✅ 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>.

---