Advance ClanX

Minecraft 版本： 1.21 1.21.1 1.21.2 1.21.3 1.21.4 1.21.5 1.21.6 1.21.7 1.21.8 1.21.9 1.21.10 1.21.11

平台： bukkit paper purpur spigot

标签： management

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

Leader/Admin Commands

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.