VIP Death Chest

# 💎📦☠️ VIP Death Chest — Premium Death Protection for VIP Players

> **Your VIPs die in style — items safe in a chest, not scattered on the ground.**

---

## 🌟 What is VIP Death Chest?

**VIP Death Chest** is a premium perk plugin that protects VIP players' items on death. Instead of items scattering on the ground where anyone can grab them, a secure chest is automatically placed at the death location containing all the player's inventory.

Fully integrated with the **BellLP VIP lifecycle** — death chests automatically activate when VIP is granted and deactivate on revocation, with smart location restoration when VIP is re-granted.

---

## ✨ Features

- 📦 **Automatic Death Chests** — Chest spawns at death location containing all items
- 🔒 **Secure Storage** — Only the owner (and admins) can access the death chest
- 🔄 **Smart State System** — ChestDataManager with active/saved state tracking
- ⚡ **Auto-Activate on VIP Grant** — Chest system activates instantly via BellLP GroupSyncHandler
- ⏸️ **Auto-Deactivate on VIP Revoke** — Saves chest location and deactivates cleanly
- 🔁 **Restore on Re-Grant** — Chest restored from saved location if the block still exists
- 🧩 **Graceful Handling** — Destroyed chests are handled silently (no-op on re-grant)
- 🔑 **LuckPerms Integration** — Permission-based VIP detection via `vipdeathchest.use`
- 👑 **Admin Override** — Admins bypass all restrictions with `vipdeathchest.admin`
- ⏰ **Configurable Expiry** — Set how long death chests persist before cleanup
- 🌍 **Multi-Language** — Built-in English and Polish localization

---

## 🔄 VIP Lifecycle Integration

```
   ┌──────────────────────────────────────────────┐
   │              VIP Lifecycle Flow               │
   │                                               │
   │  BellGate ──→ BellLP ──→ VIP Death Chest       │
   │  (Purchase)   (Grant)    (Activate Chest)     │
   │                                               │
   │  VIP Granted ──→ Chest System: ACTIVE ✅      │
   │  VIP Revoked ──→ Chest System: SAVED ⏸️       │
   │  VIP Re-Granted ──→ Chest System: RESTORED 🔁│
   │  Chest Destroyed ──→ Silent No-Op 🧩         │
   └──────────────────────────────────────────────┘
```

### How VIP Flow Works:

1. 💳 Player purchases VIP through **BellGate**
2. 🔑 **BellLP** grants the VIP group and permissions
3. 📦 **VIP Death Chest** auto-activates via GroupSyncHandler
4. ☠️ On death → Items stored in a chest, not dropped
5. ❌ VIP expires → Chest location saved, feature deactivated
6. 🔄 VIP renewed → Chest restored from saved location

---

## 💻 Commands

| Command | Description |
|---------|-------------|
| `/vipchest` | Check your death chest status |
| `/vipchest info` | Show detailed chest information |
| `/vipchest reload` | Reload configuration (admin only) |

---

## 🔐 Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| `vipdeathchest.use` | VIP death chest access (auto-managed by BellLP) | false |
| `vipdeathchest.admin` | Admin commands and bypass | OP |

---

## 📥 Installation

1. Download `VIP Death Chest.jar`
2. Place it in your server's `plugins/` folder
3. Restart the server
4. *(Recommended)* Install LuckPerms for permission-based VIP detection
5. *(Recommended)* Install BellLP for automatic VIP lifecycle management
6. Configure `config.yml`

---

## ⚙️ Configuration Highlights

```yaml
# Death chest settings
chest:
  duration: 3600              # Chest expiry time in seconds (0 = no expiry)
  protect-from-explosions: true
  protect-from-hoppers: true

# VIP detection
vip:
  permission: "vipdeathchest.use"
  auto-sync: true             # Sync with BellLP VIP events

# Chest data persistence
data:
  save-on-deactivate: true    # Save chest location on VIP revoke
  restore-on-reactivate: true # Restore from saved on VIP re-grant
  check-block-exists: true    # Verify block still exists before restore

# Language
language: en                  # en / pl
```

---

## 🔗 Dependencies

| Type | Plugin | Required? | Purpose |
|------|--------|-----------|---------|
| — | — | ✅ None required | Works standalone |
| Soft | LuckPerms | Recommended | Permission-based VIP detection |
| Soft | BellLP | Recommended | Full VIP lifecycle integration |

VIP Death Chest works standalone with manual permission assignment, but shines when paired with LuckPerms and BellLP for automatic VIP management.

---

## 📊 State System Explained

VIP Death Chest uses a sophisticated state management system:

| State | Description | Trigger |
|-------|-------------|---------|
| **ACTIVE** | Death chests are created on death | VIP permission granted |
| **SAVED** | Chest location stored, feature inactive | VIP permission revoked |
| **RESTORED** | Chest restored from saved location | VIP re-granted + block exists |
| **INACTIVE** | No chest data, feature off | No VIP permission / chest destroyed |

---

## 🎮 Player Experience

### VIP Player Dies:
```
☠️ You died!
📦 Your items have been safely stored in a death chest.
📍 Location: x:123, y:64, z:-456
⏰ Chest expires in: 1 hour
```

### Non-VIP Player Dies:
```
☠️ You died!
💡 Tip: VIP players get automatic death chests!
```

---

## 🤝 Part of the Bell Ecosystem

VIP Death Chest is designed to work seamlessly within the Bell plugin ecosystem:

- **BellGate** → Player purchases VIP
- **BellLP** → VIP group granted, permissions synced
- **VIP Death Chest** → Death chest auto-activated
- **ServerGuard** → Death chest events logged

---

## 📋 Requirements

- ☕ **Java 21+**
- 🖧 **Paper or Spigot 1.21+**
- 💾 No required dependencies (LuckPerms + BellLP recommended)

---

## 🆘 Support

- 💬 **Discord:** [https://discord.gg/6q7bnSYaR](#)
- 🐛 **Issues:** [GitHub Issues](#)
- 📖 **Wiki:** [Documentation](#)
- 💡 **Feature Requests:** [Submit ideas](#)

---

## 📄 License

VIP Death Chest is developed and maintained as part of the Bell plugin ecosystem.

---

> 💎 *Give your VIPs the premium treatment — because dying shouldn't mean losing everything.*