# CocoVaults

**CocoVaults-Premium** is an advanced and powerful virtual vault plugin for Minecraft servers. This premium plugin provides players with personal storage containers accessible from anywhere, featuring multiple storage backends, advanced caching systems, database integrity checks, and comprehensive administrative tools for optimal performance.

### Main Features

#### 🏦 Advanced Virtual Storage System

* **Personal Vaults**: Each player gets their own set of virtual storage containers
* **GUI Management**: Intuitive graphical interface for vault access and management
* **Unlimited Capacity**: Each vault provides 54 slots of storage (double chest size)
* **Permission-based System**: Configure vault quantity and access based on player permissions
* **Vault Unlocking**: Special permission system for unlocking specific vault numbers

#### 💾 Multiple Storage Backends

* **YAML**: Simple file-based storage for small servers
* **JSON**: Modern file-based storage with better performance
* **SQLite**: Local database storage for better reliability
* **MySQL**: Remote database storage for multi-server setups
* **MariaDB**: Alternative MySQL-compatible database support
* **Connection Pooling**: Advanced database connection management

#### ⚡ Premium Performance Features

* **Smart Caching**: Intelligent cache system with automatic expiration
* **Async Operations**: Non-blocking database operations for optimal performance
* **Database Integrity**: Automatic data corruption detection and recovery
* **Backup System**: Automatic data backup and recovery mechanisms
* **Cache Maintenance**: Automated cache cleanup and optimization

#### 🎨 Advanced Customization & Management

* **Custom Vault Icons**: Players can personalize their vault appearances
* **Vault Renaming**: Custom names with color code support
* **Item Blacklist**: Prevent specific items from being stored
* **Admin Tools**: Complete administrative control over player vaults
* **Cooldown System**: Configurable vault access cooldowns

### Configuration

#### Complete Configuration File

```yaml
# Version of the configuration file / plugin, do not
# modify this file or you will disrupt the
# version and a new file will be created.
Config-Version: 3.1
Plugin-Version: 3.2-ALPHA

#######################
##  Storage Settings ##
#######################
# Plugin Storage, you can edit them according to your needs.
Storage-Mode:
  # Try migrating your data to a safer operation like JSON or SQLite
  Mode: JSON # Available: YAML, MySQL, MariaDB, SQLite, JSON

  # Connection pool configuration for SQL databases
  Connection-Pool-Settings:
    max-connections: 20       # Maximum simultaneous connections
    min-idle: 5               # Minimum of inactive connections maintaining
    connection-timeout: 30000 # Maximum waiting time for connection (MS)
    max-lifetime: 1800000     # Maximum life of a connection (MS)

  # Specific configurations for each database engine
  MySQL-Data:
    host: 127.0.0.1
    port: 3306
    name: DatabaseName
    user: root
    password: root

  MariaDB-Data:
    host: 127.0.0.1
    port: 3310
    name: DatabaseName
    user: root
    password: root

  SQLite-Data:
    file: Storage/database.db

#########################
##  Plugin Permissions ##
#########################
# The vault permissions is: cocovaults.quantity.X
Plugin-Permissions:
  ALL: cocovaults.*
  Open-Vaults: cocovaults.open
  Admin-Vaults: cocovaults.admin
  Change-Icons: cocovaults.icons
  Rename: cocovaults.rename
  Rename-Color: cocovaults.rename.color
  GUI-Access: cocovaults.gui

######################
##  Plugin Messages ##
######################
# Plugin messages, you can edit them according to your needs.
Messages:
  Prefix: '<aqua>Coco</aqua><white>Vaults</white> <dark_gray><bold>» </bold></dark_gray>'
  No-Perms: "<red>You don't have permissions to run this command"
  No-Subcmd: "<red>This command doesn't exist"
  No-Player-Found: "<red>This player doesn't exist"
  Reloading: "<yellow>Reloading..."
  Reloaded-Success: "<green>Config was reloaded correctly"
  Only-players: "<red>This command can only be used by players"
  Full-Space: "<red>You can't fit any more things in your Vault"
  No-More-Vaults: "<red>You cannot open more vaults"
  No-Admin: "<red>You cannot open other players' Vaults"
  Blacklisted-Item: "<red>You can't save this in Vaults"
  Opened-Vault: "<green>Vault %vault% <green>opened successfully"
  Changed-Icon: "<green>Vault icon changed correctly"
  Analysis-Error: "<red>There was an error when making this request"
  Saved-Vault: "<green>Vault closed correctly"
  Invalid-Material: "<red>Invalid item material."
  Vault-Deleted: "<red>Vault deleted successfully."
  Vault-Restored: "<green>Vault restored successfully"
  Data-Loading-Error: "<red>Plugin data has not loaded yet"
  Data-Loading-Please-Wait: "<red>Please Wait, Loading data..."
  GUI-Item-Name: "<white>CocoVault <green>%vault%"
  Vault-Closed-Due-To-Inactivity: "<red>The vault was closed due to inactivity"
  No-Valid-Count-Give: '<red>Invalid number of Vaults'
  Gived-Vaults: '<green>You gave %count% number of Vaults to %player%'
  Conversion-Started: "<yellow>Starting conversion of all data from PlayerVaultsX..."
  Conversion-Complete: "<green>Conversion from PlayerVaultsX has completed successfully! %vaults% %players% player vaults have been converted."
  Import-Confirmation: "<yellow>This action will overwrite existing data. Enter the command again to confirm the import."
  Specify-Vault: "<red>Please specify a Vault number or name."
  Vault-Renamed: "<green>Vault renamed to %vault%."
  Invalid-Vault: "<red>Vault invalid or not found."
  Removed-Vaults: "<green>%count% Vaults have been successfully removed from player %player%."
  No-Valid-Count-Remove: "<red>Please specify a valid number of Vaults to remove."
  Not-Enough-Vaults-To-Remove: "<red>The player currently has additional %current% Vaults. You cannot remove %requested% Vaults."
  Vault-Removed: "<green>Vault %vault% has been successfully removed."
  Additional-Vaults-Updated: "<green>The number of additional Vaults has been updated to %current%."
  Vault-Closed-Due-To-Deletion: "<red>One of your Vaults has been deleted by an administrator."
  Storage-Mode-Invalid: "<red>The specified storage mode is invalid or not supported."
  Opened-Vault-Admin: "<green>You have opened the Vault %Vault% of %Player%."
  Vault-Closed: "<green>You have closed your vault."
  Wait-Cooldown: "<red>You must wait %seconds% seconds to open your cocovault again."
  Import-Not-Possible: "<red>Import is not possible. Please Check Console Log"
  Vault-Locked-By-Admin: "<red>Your Vault has been closed because an administrator has edited it."
  Vault-Updated-By-Admin: "<yellow>Your Vault has been updated by an administrator."
  Vault-Locked: "<red>You don't have access to this vault."

####################
##  GUI Settings  ##
####################
# General adjustment of GUIs
GUIs:
  Vault-List-GUI: "<black>CocoVaults GUI - Page %page%"
  GUI-Item-Name: "<white>CocoVault <green>%vault%"
  Player-Vault: "<black>CocoVault %vault%"
  Next-Page-Button: "<white>Next Page ➡"
  Previous-Page-Button: "<white>⬅ Previous Page"

# GUI Items
GUI-Items:
  Default-Vault: CHEST
  Lore-Vaults:
    - '<green>CocoVault - Virtual Chest'
    - ''
    - '<green>Open your CocoVault and access'
    - '<green>your remote storage'
    - ''
    - '<yellow>Occupied space: <white>[<green>%usage%<white>/<dark_gray>54<white>]'
    - '<yellow>Free space: <white>[<green>%free%<white>/<dark_gray>54<white>]'
    - ''
    - '<yellow>Click to open the CocoVault'
  Decoration: BLACK_STAINED_GLASS_PANE
  Next-Page-Item: ARROW
  Previous-Page-Item: ARROW

#################################
##  Miscellaneous Adjustments  ##
#################################
# Important to determine the utility
# and plugin rules
Misc-Settings:
  Max-Vaults: 100
  Open-Cooldown: 1 # 1 second, Useful to avoid problems with openness, -1 to disable. Accept decimal values (float)
  Close-Opens-Main-GUI: false # Close Vault opens the main gui?
  Open-Sound: BLOCK_ENDER_CHEST_OPEN # What sound does Vault do when you open it?
  Close-Sound: BLOCK_ENDER_CHEST_CLOSE # What sound does Vault do when you close it?

######################
##  Item Blacklist  ##
######################
# What should not enter the
# Vaults of the players?
Item-BlackList:
  - DIAMOND_BLOCK
  - DIAMOND
```

### Configuration Options

#### Storage Settings

**Storage-Mode**

* **Mode**: `YAML/JSON/SQLite/MySQL/MariaDB` - Choose your preferred storage backend
  * `YAML`: Simple file-based storage
  * `JSON`: Optimized file-based storage
  * `SQLite`: Local database storage
  * `MySQL`: Remote MySQL database
  * `MariaDB`: Remote MariaDB database

**Connection-Pool-Settings&#x20;*****(Database only)***

* **max-connections**: `20` - Maximum simultaneous database connections
* **min-idle**: `5` - Minimum inactive connections to maintain
* **connection-timeout**: `30000` - Maximum wait time for connection (milliseconds)
* **max-lifetime**: `1800000` - Maximum lifetime of a connection (milliseconds)

**Database Configuration**

**MySQL-Data** / **MariaDB-Data**:

* **host**: Database server hostname
* **port**: Database server port (3306 for MySQL, 3310 for MariaDB)
* **name**: Database name
* **user**: Database username
* **password**: Database password

**SQLite-Data**:

* **file**: `Storage/database.db` - Path to SQLite database file

#### Plugin Permissions

**Permission Nodes**

* **ALL**: `cocovaults.*` - All plugin permissions
* **Open-Vaults**: `cocovaults.open` - Permission to open vaults
* **Admin-Vaults**: `cocovaults.admin` - Administrative vault access
* **Change-Icons**: `cocovaults.icons` - Permission to change vault icons
* **Rename**: `cocovaults.rename` - Permission to rename vaults
* **Rename-Color**: `cocovaults.rename.color` - Permission to use color codes in names
* **GUI-Access**: `cocovaults.gui` - Permission to access GUI

#### Plugin Messages

All plugin messages support MiniMessage formatting and include:

* **Prefix**: Plugin message prefix with color formatting
* **No-Perms**: No permission message
* **No-Subcmd**: Invalid subcommand message
* **No-Player-Found**: Player not found message
* **Reloading**: Plugin reload in progress message
* **Reloaded-Success**: Successful reload message
* **Only-players**: Player-only command message
* **Full-Space**: Vault full message
* **No-More-Vaults**: Maximum vaults reached message
* **No-Admin**: No admin permission message
* **Blacklisted-Item**: Blacklisted item message
* **Opened-Vault**: Vault opened message (supports `%vault%` variable)
* **Changed-Icon**: Icon changed message
* **Analysis-Error**: Error analysis message
* **Saved-Vault**: Vault saved message
* **Invalid-Material**: Invalid material message
* **Vault-Deleted**: Vault deleted message
* **Vault-Restored**: Vault restored message
* **Data-Loading-Error**: Data loading error message
* **Data-Loading-Please-Wait**: Data loading wait message
* **GUI-Item-Name**: GUI item display name (supports `%vault%` variable)
* **Vault-Closed-Due-To-Inactivity**: Inactivity closure message
* **No-Valid-Count-Give**: Invalid vault count message
* **Gived-Vaults**: Vaults given message (supports `%count%` and `%player%` variables)
* **Conversion-Started**: Conversion start message
* **Conversion-Complete**: Conversion complete message (supports `%vaults%` and `%players%` variables)
* **Import-Confirmation**: Import confirmation message
* **Specify-Vault**: Specify vault message
* **Vault-Renamed**: Vault renamed message (supports `%vault%` variable)
* **Invalid-Vault**: Invalid vault message
* **Removed-Vaults**: Vaults removed message (supports `%count%` and `%player%` variables)
* **No-Valid-Count-Remove**: Invalid remove count message
* **Not-Enough-Vaults-To-Remove**: Insufficient vaults message (supports `%current%` and `%requested%` variables)
* **Vault-Removed**: Single vault removed message (supports `%vault%` variable)
* **Additional-Vaults-Updated**: Vault count updated message (supports `%current%` variable)
* **Vault-Closed-Due-To-Deletion**: Vault deleted by admin message
* **Storage-Mode-Invalid**: Invalid storage mode message
* **Opened-Vault-Admin**: Admin vault access message (supports `%Vault%` and `%Player%` variables)
* **Vault-Closed**: Vault closed message
* **Wait-Cooldown**: Cooldown wait message (supports `%seconds%` variable)
* **Import-Not-Possible**: Import failed message
* **Vault-Locked-By-Admin**: Admin locked vault message
* **Vault-Updated-By-Admin**: Admin updated vault message
* **Vault-Locked**: Locked vault access message

#### GUI Settings

**GUI Names**

* **Vault-List-GUI**: `<black>CocoVaults GUI - Page %page%` - Main GUI title (supports `%page%` variable)
* **GUI-Item-Name**: `<white>CocoVault <green>%vault%` - Vault item name (supports `%vault%` variable)
* **Player-Vault**: `<black>CocoVault %vault%` - Individual vault title (supports `%vault%` variable)
* **Next-Page-Button**: `<white>Next Page ➡` - Next page button text
* **Previous-Page-Button**: `<white>⬅ Previous Page` - Previous page button text

**GUI Items**

* **Default-Vault**: `CHEST` - Default vault icon material
* **Lore-Vaults**: List of lore lines for vault items (supports `%usage%` and `%free%` variables)
* **Decoration**: `BLACK_STAINED_GLASS_PANE` - GUI decoration item
* **Next-Page-Item**: `ARROW` - Next page button material
* **Previous-Page-Item**: `ARROW` - Previous page button material

#### Miscellaneous Settings

**Misc-Settings**

* **Max-Vaults**: `100` - Maximum number of vaults per player
* **Open-Cooldown**: `1` - Cooldown in seconds between vault openings (-1 to disable, accepts decimals)
* **Close-Opens-Main-GUI**: `false` - Whether closing a vault opens the main GUI
* **Open-Sound**: `BLOCK_ENDER_CHEST_OPEN` - Sound played when opening a vault
* **Close-Sound**: `BLOCK_ENDER_CHEST_CLOSE` - Sound played when closing a vault

#### Item Blacklist

**Item-BlackList**

List of materials that cannot be stored in vaults:

* Example items: `DIAMOND_BLOCK`, `DIAMOND`
* Supports any valid Minecraft material name
* Case-sensitive material names

### Commands

#### `/cocovaults` or `/cv`

Main command for all vault operations.

**Basic Commands**

**`/cv`**

* **Description**: Open the vault GUI
* **Permission**: `cocovaults.open`
* **Usage**: `/cv` or `/cocovaults`

**`/cv <number>`**

* **Description**: Open a specific vault by number
* **Permission**: `cocovaults.open`
* **Usage**: `/cv 1`, `/cv 5`
* **Note**: Vault number must be within player's limit or unlocked

**`/cv reload`**

* **Description**: Reload plugin configuration
* **Permission**: `cocovaults.admin`
* **Usage**: `/cv reload`

**Administrative Commands**

**`/cv admin <player> <vault>`**

* **Description**: Open another player's vault (admin mode)
* **Permission**: `cocovaults.admin`
* **Usage**: `/cv admin PlayerName 1`
* **Effect**: Opens player's vault with admin access

**`/cv give <player> <amount>`**

* **Description**: Give additional vaults to a player
* **Permission**: `cocovaults.admin`
* **Usage**: `/cv give PlayerName 5`
* **Effect**: Adds extra vaults to player's limit

**`/cv remove <player> <amount>`**

* **Description**: Remove vaults from a player
* **Permission**: `cocovaults.admin`
* **Usage**: `/cv remove PlayerName 2`
* **Effect**: Reduces player's vault count

**`/cv delete <player> <vault>`**

* **Description**: Delete a specific vault
* **Permission**: `cocovaults.admin`
* **Usage**: `/cv delete PlayerName 3`
* **Effect**: Permanently deletes the specified vault

**`/cv rename <vault> <name>`**

* **Description**: Rename a vault
* **Permission**: `cocovaults.rename`
* **Usage**: `/cv rename 1 "My Storage"`
* **Effect**: Changes vault display name

**`/cv icon <vault>`**

* **Description**: Change vault icon to held item
* **Permission**: `cocovaults.icons`
* **Usage**: Hold desired item and use `/cv icon 1`
* **Effect**: Changes vault icon in GUI

**`/cv convert playervaultsx`**

* **Description**: Import data from PlayerVaultsX
* **Permission**: `cocovaults.admin`
* **Usage**: `/cv convert playervaultsx`
* **Effect**: Migrates data from PlayerVaultsX plugin

**`/cv storage <mode>`**

* **Description**: Switch storage backend
* **Permission**: `cocovaults.admin`
* **Usage**: `/cv storage JSON`, `/cv storage MySQL`
* **Effect**: Changes active storage system

### Permissions

#### Basic Permissions

| Permission                | Description                    | Default     |
| ------------------------- | ------------------------------ | ----------- |
| `cocovaults.open`         | Open personal vaults           | All Players |
| `cocovaults.gui`          | Access vault GUI               | All Players |
| `cocovaults.rename`       | Rename vaults                  | All Players |
| `cocovaults.rename.color` | Use color codes in vault names | All Players |
| `cocovaults.icons`        | Change vault icons             | All Players |

#### Administrative Permissions

| Permission         | Description                  | Default |
| ------------------ | ---------------------------- | ------- |
| `cocovaults.admin` | All administrative functions | OP      |
| `cocovaults.*`     | All plugin permissions       | OP      |

#### Vault Quantity Permissions

| Permission                     | Description                         | Default |
| ------------------------------ | ----------------------------------- | ------- |
| `cocovaults.quantity.<number>` | Access to specific number of vaults | None    |
| `cocovaults.unlocked.<number>` | Unlock specific vault number        | None    |

**Examples:**

* `cocovaults.quantity.5` - Player can have 5 vaults
* `cocovaults.quantity.20` - Player can have 20 vaults
* `cocovaults.unlocked.50` - Player can access vault #50 specifically

### Available Variables

In messages and GUI elements you can use the following variables:

* `%vault%` - Vault number or name
* `%player%` - Player name
* `%page%` - GUI page number
* `%usage%` - Number of used slots in vault
* `%free%` - Number of free slots in vault
* `%count%` - Count of vaults
* `%current%` - Current number of vaults
* `%requested%` - Requested number of vaults
* `%vaults%` - Total vaults converted
* `%players%` - Total players processed
* `%seconds%` - Cooldown time in seconds
* `%Vault%` - Vault number (capitalized)
* `%Player%` - Player name (capitalized)

### Premium Features

#### Database Integrity System

* **Corruption Detection**: Automatic detection of corrupted vault data
* **Data Recovery**: Automatic recovery from backup data
* **Integrity Verification**: Real-time data integrity checks
* **Backup Creation**: Automatic backup before critical operations

#### Advanced Caching

* **Smart Cache**: Intelligent caching with automatic expiration
* **Cache Versioning**: Version control for cache consistency
* **Memory Optimization**: Efficient memory usage with cleanup
* **Thread Safety**: Concurrent access protection

#### Connection Management

* **Connection Pooling**: Optimized database connection pooling
* **Connection Monitoring**: Real-time connection health checks
* **Auto-reconnection**: Automatic reconnection on connection loss
* **Connection Limits**: Configurable connection limits

#### Administrative Tools

* **Vault Locking**: Temporary vault locking during admin edits
* **Real-time Updates**: Live updates when admins modify vaults
* **Data Migration**: Easy migration between storage backends
* **Import/Export**: Data import from other vault plugins

### Storage Backend Comparison

#### File-based Storage

**YAML**

* ✅ Simple configuration
* ✅ Human-readable format
* ❌ Slower performance
* ❌ Limited scalability

**JSON**

* ✅ Better performance than YAML
* ✅ Lightweight format
* ✅ Good for small-medium servers
* ❌ Limited multi-server support

#### Database Storage

**SQLite**

* ✅ No external dependencies
* ✅ Better performance than files
* ✅ ACID compliance
* ❌ Single-server limitation

**MySQL/MariaDB**

* ✅ Multi-server support
* ✅ Excellent performance
* ✅ Advanced features
* ✅ Professional scalability
* ❌ Requires external database

### How It Works

#### Vault Access System

1. **Permission Check**: Verifies player has access to requested vault
2. **Cache Validation**: Checks if vault data is cached and valid
3. **Data Loading**: Loads vault data from storage if needed
4. **Integrity Verification**: Verifies data integrity (Premium feature)
5. **GUI Creation**: Creates and displays vault interface
6. **Activity Tracking**: Tracks player activity for inactivity management

#### Caching System

1. **Smart Loading**: Loads vault data on demand
2. **Cache Validation**: Automatic cache expiration and validation
3. **Memory Management**: Intelligent memory cleanup
4. **Thread Safety**: Concurrent access protection
5. **Data Synchronization**: Real-time data synchronization

#### Database Operations

1. **Connection Pooling**: Efficient connection management
2. **Async Operations**: Non-blocking database operations
3. **Integrity Checks**: Data corruption detection and recovery
4. **Backup Management**: Automatic backup creation and restoration
5. **Migration Tools**: Easy data migration between backends

### Installation

#### Basic Installation

1. Download CocoVaults-Premium plugin
2. Place the `.jar` file in your server's `plugins/` folder
3. Restart the server
4. Configure the generated `config.yml` file
5. Set up permissions as needed
6. Use `/cv reload` to apply changes

#### Database Setup (Optional)

**MySQL/MariaDB Setup**

1. Create a database for CocoVaults
2. Create a user with appropriate permissions
3. Configure database settings in config:

   ```yaml
   Storage-Mode:
     Mode: MySQL
     MySQL-Data:
       host: your-database-host
       port: 3306
       name: cocovaults_database
       user: cocovaults_user
       password: your_password
   ```
4. Reload the plugin to activate database storage

**SQLite Setup**

1. Configure SQLite in config:

   ```yaml
   Storage-Mode:
     Mode: SQLite
     SQLite-Data:
       file: Storage/cocovaults.db
   ```
2. Reload the plugin to create the database file

#### Migration from Other Plugins

1. Install CocoVaults-Premium
2. Use the import command: `/cv convert playervaultsx`
3. Verify data migration was successful
4. Remove the old vault plugin

### Troubleshooting

#### Common Issues

**Vaults not loading**

* Check storage backend configuration
* Verify database connection settings
* Check server logs for error messages
* Ensure proper permissions are set

**Database connection errors**

* Verify database server is running
* Check connection settings in config
* Ensure database user has proper permissions
* Check network connectivity

**Permission issues**

* Verify permission nodes are correctly set
* Check vault quantity permissions
* Ensure players have basic access permissions
* Test with admin permissions first

**Performance issues**

* Check cache settings and expiration
* Monitor database connection pool
* Review server resources
* Consider storage backend upgrade

#### Debug Information

* Plugin logs important events to console
* Configuration validation on startup
* Database connection monitoring
* Cache performance metrics

### Performance Optimization

#### Recommended Settings

**Small Servers (1-50 players)**

```yaml
Storage-Mode:
  Mode: JSON
Connection-Pool-Settings:
  max-connections: 5
  min-idle: 2
```

**Medium Servers (50-200 players)**

```yaml
Storage-Mode:
  Mode: SQLite
Connection-Pool-Settings:
  max-connections: 10
  min-idle: 3
```

**Large Servers (200+ players)**

```yaml
Storage-Mode:
  Mode: MySQL
Connection-Pool-Settings:
  max-connections: 20
  min-idle: 5
```

### Support

For support, bug reports, or feature requests:

* **Discord**: <https://fruitforge.com/discord>

***

*Premium plugin developed by FruitForge Studio*