CubeClans

What's Included

📦 Installation

1. Download CubeClans.jar and place it inside your server's plugins/ directory.
2. Restart your server. Configuration files will be generated automatically in plugins/CubeClans/.
3. (Optional) Install Vault along with an economy plugin (like EssentialsX) to enable clan creation costs and clan bank features.
4. (Optional) Install PlaceholderAPI to utilize %cubeclans_*% placeholders across your scoreboards, tablists, and chat formatting plugins.
5. Modify config.yml, messages.yml, and ranks.yml to customize plugin behavior to your server's style.
6. Run /clan admin reload to reload configuration files without restarting the server.

Soft Dependencies

💬 Commands

All player and administrative commands use the main root command /clan. Aliases: /clans, /c.

Player Commands

Admin Commands

🔑 Permissions

🎰 GUI System

Executing /clan opens the main menu inventory. All items, glass panes, slots, and lores are fully configurable in config.yml with Hex color support (#RRGGBB).

Menu Navigation

📦 Upgradable Clan Chest

CubeClans includes a built-in shared vault accessible via /clan chest. The chest capacity grows dynamically as your clan levels up.

Slot Progression Formula

Base slots start at 9 slots (1 row) at Level 1. Every levels-per-upgrade (default: 3 levels), the clan unlocks 9 additional slots up to a maximum of 54 slots (6 rows).

📈 Level & XP System

Clans earn XP and level up based on PvP activity. Every kill made by a member adds points, while deaths penalize clan progression.

Points & Formula

XP required to reach each level follows an exponential curve:

# Formula: points_needed = ceil(base-points * level^level-exponent)
base-points: 100
level-exponent: 1.5

• Level 1 → 2: 100 XP
• Level 2 → 3: 283 XP
• Level 3 → 4: 520 XP
• Level 4 → 5: 800 XP

⚔ Alliances & Enemies

Clans can manage diplomatic relations with rival factions. Limits are configurable in config.yml (Default: 3 Allies, 5 Enemies).

Features

• Alliance Requests: Command /clan ally <clan> sends a request requiring acceptance by the target clan leader.
• Allies Chat: Toggle dedicated ally communications with /clan chat ally.
• Enemy Declarations: Declare rival clans as enemies using /clan enemy <clan> without requiring target consent.
• Friendly Fire Protection: Toggle PvP between clan members using /clan pvp.

🏦 Clan Bank Economy

Requires Vault and an economy provider plugin. Clans feature a shared financial bank.

👑 Ranks & Hierarchy

CubeClans allows complete custom rank ladders via ranks.yml. Each rank defines display names, ladder position, chat prefix, and permissions.

Default Rank Hierarchy

🎨 Chat & Colors

CubeClans offers custom color codes and hex codes (#RRGGBB) for clan display names.

• Clan Chat: Switch to internal clan chat with /clan chat. Format: &e&lCHAT CLAN » &8[&b%clan%&8] &7%player%: &f%message%
• Allies Chat: Switch to alliance chat with /clan chat ally. Format: &d&lCHAT ALLY » &8[&b%clan%&8] &7%player%: &f%message%
• HEX Clan Colors: Select custom colors via the GUI or type #RRGGBB when prompted. Cooldown configurable in config.yml.

⚙ Configuration Files

All configuration files reside in plugins/CubeClans/. Changes are applied using /clan admin reload.

config.yml

Database Configuration

database:
  type: SQLITE # SQLITE or MYSQL
  mysql:
    host: localhost
    port: 3306
    database: cubeclans
    username: root
    password: password
    pool:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout: 5000

General Settings

settings:
  min-clan-name-length: 3
  max-clan-name-length: 16
  max-clan-members: 10
  max-clan-allies: 3
  max-clan-enemies: 5
  allow-colors-in-names: true
  clan-creation-cost: 300 # Requires Vault

messages.yml

Customizable text output with placeholders such as %clan%, %player%, %cost%, %color%, and {level}.

prefix: "&8[&bCubeClans&8]&r"
clan-created: "&aSuccessfully created clan &f%clan%&a!"
clan-deleted: "&aClan successfully deleted!"
level-up: "&a&lLEVEL UP! &eYou reached level &6{level}&e!"

ranks.yml

Defines the rank structure, permissions, and ladder positions.

ranks:
  leader:
    display-name: "&aLeader"
    prefix: "&8[%color%**%clan%&8] &r"
    ladder-position: 2
    permissions:
      - 'ALL'
  member:
    display-name: "&9Member"
    prefix: "&8[%color%%clan%&8] &r"
    ladder-position: 0
    default: true
    permissions:
      - 'BANK_DEPOSIT'
      - 'BANK_WITHDRAW'
      - 'BANK_BALANCE'
      - 'CHAT'

🔌 PlaceholderAPI

CubeClans registers official placeholders for tablists, scoreboards, and chat extensions.

🔄 Data Migration Tool

Easily import legacy clan data using the built-in administrator migration tool.

# Command usage:
/clan admin migrate <PluginName>