# 🛡️ Clans Документация (v1.5.0)

## 🎯 Основные Команды

### Команды управления кланом (/clan)

| Команда | Описание | Пример использования |
|---------|----------|---------------------|
| /clan create <имя> | Создать новый клан | /clan create MyTeam |
| /clan delete | Удалить свой клан | /clan delete |
| /clan rename <имя> | Переименовать клан | /clan rename NewName |
| /clan upgrade | Улучшить уровень клана | /clan upgrade |
| /clan info [клан] | Показать информацию о клане | /clan info или /clan info MyTeam |
| /clan list | Список всех кланов на сервере | /clan list |
| /clan top [тип] | Рейтинг кланов | /clan top level |

### Команды управления участниками

| Команда | Описание | Пример использования |
|---------|----------|---------------------|
| /clan invite <игрок> | Пригласить игрока в клан | /clan invite Steve |
| /clan accept | Принять приглашение в клан | /clan accept |
| /clan deny | Отклонить приглашение в клан | /clan deny |
| /clan kick <игрок> | Исключить игрока из клана | /clan kick Alex |
| /clan leave | Покинуть клан | /clan leave |
| /clan setrank <игрок> <ранг> | Изменить ранг участника | /clan setrank Steve officer |

### Команды экономики

| Команда | Описание | Пример использования |
|---------|----------|---------------------|
| /clan donate <сумма> | Пожертвовать деньги в казну клана | /clan donate 1000 |
| /clan withdraw <сумма> | Снять деньги из казны (только лидер) | /clan withdraw 500 |

### Команды прогрессии

| Команда | Описание | Пример использования |
|---------|----------|---------------------|
| /clan addexp <количество> | Добавить опыт клану | /clan addexp 100 |

---

## 🎨 GUI Команды

| Команда | Описание |
|---------|----------|
| /clanmenu | Открыть графическое меню клана |

Алиасы: /cm, /clanm

---

## 🔧 Админ Команды

### Команды администратора (/clanadmin)

| Команда | Описание | Пример использования | Права |
|---------|----------|---------------------|-------|
| /clanadmin reload | Перезагрузить все конфигурации | /clanadmin reload | clan.admin |
| /clanadmin setlevel <клан> <уровень> | Установить уровень клана | /clanadmin setlevel MyTeam 10 | clan.admin |
| /clanadmin addmoney <клан> <сумма> | Добавить деньги в казну клана | /clanadmin addmoney MyTeam 5000 | clan.admin |
| /clanadmin removemoney <клан> <сумма> | Убрать деньги из казны клана | /clanadmin removemoney MyTeam 1000 | clan.admin |

Алиасы: /cadmin, /ca

---

## 🔌 PlaceholderAPI Интеграция

### 📋 Установка

PlaceholderAPI определяется автоматически при старте плагина. Никакой дополнительной настройки не требуется!

### 📊 Доступные Плейсхолдеры

#### Основные данные клана

| Плейсхолдер | Описание | Пример вывода |
|-------------|----------|---------------|
| %clan_name% | Название клана | MyTeam |
| %clan_name_colored% | Цветное название клана | §6MyTeam |
| %clan_tag% | Тег клана | MT |
| %clan_tag_colored% | Цветной тег клана | §bMT |
| %clan_level% | Текущий уровень клана | 15 |
| %clan_level_colored% | Цветной уровень клана | §a15 |
| %clan_level_prefix% | Префикс оформления уровня | &8[ |
| %clan_level_suffix% | Суффикс оформления уровня | &8] |
| %clan_level_full% | Полностью оформленный уровень | &8[&a15&8] |
| %clan_progress_percent% | Процент до след. уровня | 15.5 |
| %clan_rank% | Ранг игрока в клане | Officer |
| %clan_leader% | Ник лидера клана | Steve |
| %clan_has_clan% | Есть ли у игрока клан | true/false |

#### Экономика

| Плейсхолдер | Описание | Пример вывода |
|-------------|----------|---------------|
| %clan_balance% | Баланс казны клана | 15000 |
| %clan_treasury% | Казна (альтернатива) | 15000 |
| %clan_bank_balance% | Баланс банка (альтернатива) | 15000 |
| %clan_bank_formatted% | Отформатированный баланс | 15.0K |

#### Участники

| Плейсхолдер | Описание | Пример вывода |
|-------------|----------|---------------|
| %clan_members% | Количество участников | 12 |
| %clan_member_count% | Количество участников (альт.) | 12 |
| %clan_max_members% | Максимум участников | 20 |
| %clan_online_members% | Участников в сети | 5 |

#### Статистика Клана

| Плейсхолдер | Описание | Пример вывода |
|-------------|----------|---------------|
| %clan_kills% | Убийства клана | 234 |
| %clan_deaths% | Смерти клана | 89 |
| %clan_kdr% | KDR клана | 2.63 |
| %clan_experience% | Опыт клана | 5400 |
| %clan_experience_formatted% | Отформатированный опыт | 5.4K |

#### Личная Статистика Игрока

| Плейсхолдер | Описание | Пример вывода |
|-------------|----------|---------------|
| %clan_player_kills% | Убийства игрока | 50 |
| %clan_player_deaths% | Смерти игрока | 10 |
| %clan_player_kdr% | KDR игрока | 5.00 |
| %clan_player_contribution% | Вклад в опыт | 1200 |

#### Позиции в рейтинге

| Плейсхолдер | Описание | Пример вывода |
|-------------|----------|---------------|
| %clan_top_position_level% | Позиция по уровню | 3 |
| %clan_top_position_treasury% | Позиция по казне | 1 |
| %clan_top_position_kills% | Позиция по убийствам | 5 |

### 💡 Примеры использования

#### В TabList (TAB plugin)

yaml

tablist-objective-value: '%clan_name_colored% [%clan_level_full%]'


#### В Chat (EssentialsX)

yaml

format: '{clan_tag_colored} &r{DISPLAYNAME}&r: {MESSAGE}'


#### В Scoreboard (FeatherBoard)

yaml

lines:

  - '&6Клан: &e%clan_name%'

  - '&6Уровень: &e%clan_level_full%'

  - '&6Казна: &a$%clan_bank_formatted%'


> 📝 Примечание: Для игроков без клана большинство плейсхолдеров вернут "No Clan" или 0.

---

## ⚙️ Конфигурация

### 📄 config.yml

yaml

клан:

  стоимость-создания: 1000.0          # Стоимость создания клана

  минимальная-длина-имени: 3          # Минимальная длина названия

  максимальная-длина-имени: 16        # Максимальная длина названия

  базовое-количество-участников: 10   # Начальные слоты участников

  участников-за-уровень: 2            # +2 слота за каждый уровень



база-данных:

  тип: sqlite                         # sqlite или mysql

  хост: localhost                     # Для MySQL

  порт: 3306

  имя-бд: clans

  пользователь: root

  пароль: ''



экономика:

  налог-включен: false                # Автоматический налог с участников

  процент-налога: 5.0                 # 5% от дохода

  взнос-при-вступлении: 0.0          # Вступительный взнос



уровни:

  множитель-опыта: 1000              # Опыт для след. уровня: level × 1000

  максимальный-уровень: 100



возможности:

  hex-цвета: true                    # Поддержка #RRGGBB цветов

  placeholderapi: true               # PlaceholderAPI интеграция



цвета:

  основной: '#FFD700'                # Золотой

  успех: '#00FF00'                   # Зелёный

  ошибка: '#FF4444'                  # Красный

  информация: '#55FFFF'              # Голубой

  предупреждение: '#FFAA00'          # Оранжевый

  акцент: '#FF69B4'                  # Розовый


### 📈 Система уровней

Формула опыта:
требуемый_опыт = уровень × множитель_опыта


Пример: Для достижения 5 уровня:
5 × 1000 = 5000 опыта


Награды за уровень:
- +2 слота участников за каждый уровень

### 💰 Экономика

| Действие | Стоимость | Настраивается |
|----------|-----------|---------------|
| Создание клана | 1000$ | ✅ Да |
| Переименование | 5000$ | ❌ Нет (фиксировано) |

Налоги:
- Опционально включаемые
- Процент от дохода участников
- Настраивается в конфиге

---

## 🔐 Система Разрешений

### Базовые права

| Разрешение | Описание | По умолчанию |
|-----------|----------|--------------|
| clan.use | Основные команды клана | true |
| clan.create | Создание клана | true |
| clan.admin | Административные команды | op |

### Настройка в LuckPerms

yaml

groups:

  default:

    permissions:

      - clan.use

      - clan.create

  

  moderator:

    permissions:

      - clan.admin


---

## 📊 Система Рангов

### 🏅 Доступные ранги

1. 👤 Участник (member) - базовый ранг
2. ⭐ Офицер (officer) - расширенные права
3. 👑 Лидер (leader) - полные права

### Матрица прав

| Действие | 👤 Участник | ⭐ Офицер | 👑 Лидер |
|----------|------------|-----------|---------|
| Просмотр информации | ✅ | ✅ | ✅ |
| Пожертвование в казну | ✅ | ✅ | ✅ |
| Приглашение игроков | ❌ | ✅ | ✅ |
| Исключение участников | ❌ | ✅ | ✅ |
| Снятие денег из казны | ❌ | ❌ | ✅ |
| Удаление клана | ❌ | ❌ | ✅ |
| Переименование клана | ❌ | ❌ | ✅ |
| Изменение рангов | ❌ | ❌ | ✅ |

---

## 🎨 GUI Система

### 🖥️ Главное меню (/clanmenu)

Структура инвентаря: 54 слота (6 рядов)

#### Элементы меню:

1. 📋 Информация о клане - название, уровень, казна
2. 👥 Участники - список членов клана
3. ⚙️ Настройки - доступно только лидеру
4. 🏅 Ранги - управление рангами
5. 💰 Казна - финансовые операции
6. 📅 События - клановые активности
7. 🏆 Таблица лидеров - топ кланов
8. ⭐ Топ-3 участника - лучшие игроки клана

### Настройка GUI (gui.yml)

```yaml
main-menu:
title: '&6⭐ &dМеню клана'
size: 54

items:
info:
slot: 4
material: PLAYER_HEAD
name: '&6ℹ &d{clan_name}'
lore:
- '&7Уровень: &e{clan_level}'
- '&7Участников: &e{clan_members}/{clan_max_members}'
- '&7Казна: &a${clan_treasury}'