Advance ClanX

# AdvanceClans (https://cdn.modrinth.com/data/cached_images/b6a8613305c7a7d68abbf1d9fab01d39bb48ecc3_0.webp) ](https://www.gtxgaming.co.uk/) ### 1. Plugin Overview **Name**: AdvanceClans (Advance ClanX) **Version**: 1.0 **Description**: A professional-grade, high-performance clan management system for Minecraft servers. Built with a focus on extreme scalability, minimal resource usage, and seamless player experience ### 2. Core Features (Performance) ### The Performance Analysis * **Extreme Load Handling**: Tested for **30 Kills/Deaths per second**. * **Zero TPS Impact**: All database operations (point updates, member changes) are handled **Asynchronously**. The main server thread is never blocked. * **Memory Efficiency**: Uses smart caching for online players (~10-20MB overhead). Does **NOT** use `Bukkit.getOfflinePlayer().getName()`, preventing the common "null" bug and lag. * **Scalability**: Optimized for **1,000+ members per clan** and **200+ active clans**. * **Database**: Uses **SQLite with WAL Mode** (Write-Ahead Logging) for safe, concurrent high-speed data access. ### 3. Commands & Permissions ### Player Commands | Command | Usage | Description | Permission | |:--- |:--- |:--- |:--- | | `/clan` | `/clan` | Main GUI Menu. | `clans.use` | | `/clan create` | `/clan create <name>` | Create a new clan. | `clans.create` | | `/clan join` | `/clan join <name>` | Request to join a clan. | `clans.join` | | `/clan accept` | `/clan accept` | Accept a clan invite. | `clans.accept` | | `/clan leave` | `/clan leave` | Leave current clan. | `clans.leave` | | `/clan info` | `/clan info ` | View clan statistics. | `clans.info` | | `/clan top` | `/clan top` | Leaderboard GUI. | `clans.top` | | `/clan chat` | `/clan chat` | Toggle Clan Chat mode. | `clans.chat` | | `/clan home` | `/clan home` | Teleport to clan home. | `clans.home` | ### Leader/Admin Commands | Command | Usage | Description | Permission | |:--- |:--- |:--- |:--- | | `/clan invite` | `/clan invite <p>` | Invite a player. | `clans.invite` | | `/clan kick` | `/clan kick <p>` | Kick a member. | `clans.kick` | | `/clan disband` | `/clan disband` | Delete the clan. | `clans.disband` | | `/clan sethome` | `/clan sethome` | Set home location. | `clans.sethome` | | `/clan cowner` | `/clan cowner set <p>`| Promote to Co-Owner. | `clans.cowner` | | `/clan set colour`| `/clan set colour <c>`| Change clan color. | `clans.set` | | `/forceclan delete`| `/forceclan delete <c>`| Admin: Delete clan. | `force.op` | | `/forceclan remove`| `/forceclan remove <c> <p>`| Admin: Remove member. | `force.op` | ### 4. PlaceholderAPI Integration Use these placeholders in scoreboards, tablists, or chat: * `%advanceclans_clan%` - Player's clan name. * `%advanceclans_role%` - Player's role (LEADER, COOWNER, MEMBER). * `%advanceclans_points%` - Clan's total points. * `%advanceclans_color%` - Clan's display color code. * `%clans_name%` → Shows the player's clan name. * `%clans_name_plain%` → Shows the player's clan name stripped from color codes. * `%clans_list_<#>_name%` → Shows the name of the clan at that position in the leaderboard. * `%clans_list_<#>_leader%` → Shows the leader of the clan at that position. * `%clans_list_<#>_point%` → Shows the balance of the clan at that position. Note: Replace <#> with the rank number in the leaderboard (e.g., %clans_list_1_name% for the top clan). ### 5. Technical Specifications * **Dependencies**: Requires (https://www.spigotmc.org/resources/placeholderapi.6245/). * **Database Structure**: * `clans`: Stores name, leader name, points, color, and home location. * `members`: Stores UUID, clan name, role, and **last_known_name** (prevents "null" issues). * `allies`: Stores clan alliance relationships. * **Configuration Files**: * `config.yml`: Core limits and permissions. * `msg.yml`: 100% translatable messages. * `gui.yml` / `settingsgui.yml`: Full GUI customization. ### 7. Data Saving Internal Logic The plugin employs a multi-layered approach to data integrity and performance: ### Data Storage Mechanism * **Database Engine**: SQLite with **WAL (Write-Ahead Logging)** mode. This allows the plugin to write to the database while simultaneously reading from it, preventing the "database is locked" errors common in simpler plugins. * **Schema Design**: * `clans`: Primary table for metadata (Owner name, Points, Color, Home Location). * `members`: Linking table connecting Player UUIDs to Clan names. It includes a `last_name` column which is updated every time a player joins, ensuring that even if a player changes their name or is offline, the plugin can display their name without querying the Mojang API or Bukkit's heavy `getOfflinePlayer` methods. * `allies`: A simple relationship table for clan-to-clan alliances. ### Functional Logic * **Asynchronous Execution**: Functions like `updatePoints`, `createClan`, and