AdvanceClans

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 [clan]	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 PlaceholderAPI.
• 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 forceDeleteClan run on a separate thread. This means that if the database takes 100ms to save, your server's TPS stays at a perfect 20.0.
• Smart Caching: On startup, the plugin loads all member-to-clan relationships into a HashMap<UUID, String>. This allows the plugin to check if a player is in a clan in constant time (O(1)) without ever touching the hard drive.
• Atomic Updates: Point updates use SQL arithmetic (SET points = points + ?) rather than reading, modifying, and writing back. This prevents "race conditions" where two kills happening at the exact same time might overwrite each other.
• Persistence Strategy: Data is saved immediately to the SQLite file upon any change. There is no risk of losing points if the server crashes unexpectedly.