EnderChestVault - Complete Plugin Documentation

---

📋 Overview

**EnderChestVault** is a premium-quality, open-source Minecraft plugin that completely replaces and enhances the vanilla Ender Chest system with a powerful, customizable, and persistent storage solution.

| Property | Value |
|----------|-------|
| **Plugin Name** | EnderChestVault |
| **Version** | 1.0.0 |
| **Minecraft Versions** | 1.21.1 - 1.21.11 |
| **Server Software** | Paper, Spigot, Purpur |
| **Java Version** | Java 21+ |

---

🎯 What Does This Plugin Do?

EnderChestVault intercepts vanilla Ender Chest interactions and replaces them with a **custom GUI-based vault system** that offers:

- **Variable storage sizes** based on player permissions
- **Multiple database backends** for data persistence
- **Cross-server compatibility** via MySQL
- **Offline player vault access** for admins
- **Pagination** for vaults larger than 54 slots

```
┌─────────────────────────────────────────────────────────────┐
│ VANILLA ENDER CHEST → ENDERCHESTVAULT │
├─────────────────────────────────────────────────────────────┤
│ • Fixed 27 slots → • 27 to 54 slots │
│ • No permission control → • Permission-based sizes │
│ • Local storage only → • PDC/SQLite/MySQL │
│ • No admin access → • View offline vaults │
└─────────────────────────────────────────────────────────────┘
```

---

✨ Key Features

1. 🗄️ Multiple Storage Backends

| Storage Type | Description | Best For |
|--------------|-------------|----------|
| **PDC** | PersistentDataContainer (stored on player) | Small servers, simplicity |
| **SQLite** | Local database file | Medium servers, single instance |
| **MySQL** | Remote database server | Networks, BungeeCord/Velocity |

2. 📦 Variable Vault Sizes

```
Permission Slots Rows
─────────────────────────────
ecvault.size.9 9 1
ecvault.size.18 18 2
ecvault.size.27 27 3
ecvault.size.36 36 4 1
ecvault.size.45 45 5
ecvault.size.54 54 6
```

3. 📄 Ender Vault

Vaults maximum 54 slots :

```
┌─────────────────────────────────────────────────────┐
│ Ender Vault │
├─────────────────────────────────────────────────────┤
│ [Item] [Item] [Item] [Item] [Item] [Item] [Item] │
│ [Item] [Item] [Item] [Item] [Item] [Item] [Item] │
│ [Item] [Item] [Item] [Item] [Item] [Item] [Item] │
│ [Item] [Item] [Item] [Item] [Item] [Item] [Item] │
│ [Item] [Item] [Item] [Item] [Item] [Item] [Item] │
│ [Item] [Item] [Item] [Item] [Item] [Item] [Item] │
├─────────────────────────────────────────────────────┤

```

5. 👁️ Admin Vault Access

Administrators can view and modify any player's vault, even when offline:

```
/ec open Notch → Opens Notch's vault (even if offline)
/ec open Steve → Opens Steve's vault for inspection
```

6. 🔄 Async Database Operations

All database reads/writes are **asynchronous** to prevent server lag:

```java
// Non-blocking vault loading
CompletableFuture<VaultData> loadVault(Player player);

// Non-blocking vault saving
CompletableFuture<Void> saveVault(Player player, VaultData data);
```

7. 🎨 Fully Customizable GUI

```yaml
gui:
title: "&5&lEnder Vault"
admin-title: "&c&l{player}'s Vault"
sounds:
open:
sound: "BLOCK_ENDER_CHEST_OPEN"
page-turn:
sound: "ITEM_BOOK_PAGE_TURN"
```

---

🎮 Commands

| Command | Description | Permission |
|---------|-------------|------------|
| `/ec` | Open your own vault | `ecvault.use` |
| `/enderchest` | Alias for /ec | `ecvault.use` |
| `/ec open <player>` | Open another player's vault | `ecvault.admin` |
| `/ec reload` | Reload configuration | `ecvault.admin.reload` |

---

🔐 Permissions

Player Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| `ecvault.use` | Use the Ender Vault | `true` |
| `ecvault.size.27` | 27 slot vault (3 rows) | `true` |
| `ecvault.size.54` | 54 slot vault (6 rows) | `false` |

Admin Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| `ecvault.admin` | Open other players' vaults | `op` |
| `ecvault.admin.reload` | Reload plugin config | `op` |
| `ecvault.admin.bypass` | Bypass restrictions | `op` |
| `ecvault.*` | All permissions | `op` |

---

🎯 Use Cases

1. 🏠 Survival Servers

**Problem**: Players want more storage, but vanilla ender chest is limited.

**Solution**: Grant donors/ranks larger vault sizes as perks.

```
Default Player → 27 slots (free)
VIP Rank → 54 slots
```

2. 🌐 Server Networks (BungeeCord/Velocity)

**Problem**: Ender chest contents don't sync across servers.

**Solution**: Use MySQL backend for cross-server vault synchronization.

```
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Lobby │ │ Survival│ │ Skyblock│
│ Server │────▶│ Server │────▶│ Server │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└───────────────┼───────────────┘
▼
┌─────────────┐
│ MySQL │
│ Database │
└─────────────┘
```

3. 🛡️ Admin Moderation

**Problem**: Need to check if a player is storing illegal items.

**Solution**: Use `/ec open <player>` to inspect any vault.

```
/ec open SuspiciousPlayer
→ Opens their vault for inspection
→ Works even if player is offline
→ Can remove contraband items
```

4. 💰 Economy Servers

**Problem**: Want to sell storage upgrades for in-game currency.

**Solution**: Integrate with permission plugins + economy.

```
/buy vault-upgrade 54 → Grants ecvault.size.54

```

---

📊 Comparison: Vanilla vs EnderChestVault

| Feature | Vanilla Ender Chest | EnderChestVault |
|---------|---------------------|-----------------|
| Storage Size | Fixed 27 slots | 27-54 slots |
| Permission Control | ❌ None | ✅ Full control |
| Database Options | World file only | PDC/SQLite/MySQL |
| Cross-Server Sync | ❌ No | ✅ Via MySQL |
| Admin Inspection | ❌ No | ✅ Full access |
| Offline Access | ❌ No | ✅ Yes |
| Pagination | ❌ No | ✅ Automatic |
| Custom GUI | ❌ No | ✅ Fully customizable |
| Async Operations | ❌ No | ✅ Yes |
| Sound Effects | ❌ Basic | ✅ Customizable |

---

🏗️ Technical Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│ EnderChestVault │
├──────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Command │ │ Listener │ │ VaultManager │ │
│ │ Handler │ │ Layer │ │ (Core Logic + Cache) │ │
│ └──────┬──────┘ └──────┬──────┘ └────────────┬────────────┘ │
│ │ │ │ │
│ └────────────────┼──────────────────────┘ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ StorageManager │ ← Interface │
│ │ (Abstraction) │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ PDC │ │ SQLite │ │ MySQL │ │
│ │ Storage │ │ Storage │ │ Storage │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ vaults.db │ │ Remote DB │ │
│ └─────────────┘ └─────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```

---

📈 Performance Characteristics

| Metric | Value |
|--------|-------|
| Memory Footprint | ~5-15 MB (depending on cache) |
| Vault Load Time | <50ms (cached), <200ms (database) |
| Save Operation | Async, non-blocking |
| Max Concurrent Users | Unlimited (connection pool limited) |
| Cache Hit Rate | >95% for active players |

Connection Pool Settings (MySQL)

```yaml
mysql:
pool:
maximum-pool-size: 10 Max database connections
minimum-idle: 2 Keep 2 connections ready
connection-timeout: 5000 5 second timeout
```

---

🔧 Installation Guide

Step 1: Download & Install

```bash
Place JAR in plugins folder
cp EnderChestVault-1.0.0.jar /server/plugins/

Start server to generate config
java -jar paper.jar
```

Step 2: Configure Storage

```yaml
plugins/EnderChestVault/config.yml
storage:
type: "SQLITE" or "PDC" or "MYSQL"
```

Step 3: Set Permissions

Using LuckPerms:
```bash
Give VIP rank 54 slots
/lp group vip permission set ecvault.size.54 true

Give staff admin access
/lp group staff permission set ecvault.admin true
```

Step 4: Reload & Test

```bash
/ec reload
/ec Open your vault
```

---

🎁 Feature Summary Card

```
╔═══════════════════════════════════════════════════════════╗
║ ENDERCHESTVAULT ║
╠═══════════════════════════════════════════════════════════╣
║ ✓ Variable vault sizes (9-27-54 slots) ║
║ ✓ Three storage backends (PDC/SQLite/MySQL) ║
║ ✓ Permission-based access control ║
║ ✓ Smart pagination for large vaults ║
║ ✓ Async database operations (no lag) ║
║ ✓ Admin vault inspection (online/offline) ║
║ ✓ All server support ║
║ ✓ Cross-server sync via MySQL ║
║ ✓ Customizable GUI & sounds ║
║ ✓ Full NBT/component preservation ║
║ ✓ HikariCP connection pooling ║
║ ✓ Caffeine in-memory caching ║
╠═══════════════════════════════════════════════════════════╣
║ Target: Minecraft 1.21.1 - 1.21.11 | Paper/Spigot API ║
╚═══════════════════════════════════════════════════════════╝

---

Need a server to run EnderChestVault?
Get 24/7 high-performance hosting from reliable hosting for your community!
Click here to get started with KCB Hosting