## 🎮 Команды и права доступа

### Команды для игроков

#### /report <игрок>

Описание: Открывает GUI меню для подачи жалобы на указанного игрока

Алиасы: /rep, /жалоба

Примеры использования:
/report Steve
/rep Alex
/жалоба Player123


Права: reportsystem.use

Ограничения:
- Нельзя пожаловаться на себя
- Действует кулдаун между жалобами (настраивается)
- Игрок должен быть онлайн

### Команды для администрации

#### /reports

Описание: Открывает GUI меню со списком всех жалоб для управления

Алиасы: /reps, /жалобы

Примеры использования:
/reports
/reps
/жалобы


Права: reportsystem.admin

Функционал:
- Просмотр всех жалоб с постраничной навигацией
- ЛКМ на жалобу - Удаление жалобы
- ПКМ на жалобу - Телепортация к обвиняемому игроку
- Отображение деталей (репортер, обвиняемый, причина, дата)

### Система прав доступа

| Право | Описание | По умолчанию |
|-------|----------|--------------|
| reportsystem.use | Подача жалоб командой /report | ✅ Все игроки |
| reportsystem.admin | Просмотр и управление жалобами | ❌ ОП |
| reportsystem.notify | Получение уведомлений о новых жалобах | ❌ ОП |
| reportsystem.bypass.cooldown | Обход кулдауна между жалобами | ❌ ОП |

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

bash
# Для всех игроков (подача жалоб)
/lp group default permission set reportsystem.use true

# Для модераторов
/lp group moderator permission set reportsystem.admin true
/lp group moderator permission set reportsystem.notify true

# Для администраторов
/lp group admin permission set reportsystem.bypass.cooldown true
/lp group admin permission set reportsystem.admin true
/lp group admin permission set reportsystem.notify true

# Для конкретного игрока
/lp user Steve permission set reportsystem.notify true


### Настройка прав в PermissionsEx

bash
# Для всех игроков
/pex group default add reportsystem.use

# Для модераторов
/pex group moderator add reportsystem.admin
/pex group moderator add reportsystem.notify

# Для администраторов
/pex group admin add reportsystem.bypass.cooldown


### Настройка прав в GroupManager

Отредактируйте groups.yml:

yaml
groups:
Default:
permissions:
- reportsystem.use

Moderator:
permissions:
- reportsystem.admin
- reportsystem.notify

Admin:
permissions:
- reportsystem.admin
- reportsystem.notify
- reportsystem.bypass.cooldown


---

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

### Структура config.yml

yaml
# Основные настройки
cooldown-seconds: 60 # Кулдаун между жалобами (секунды)
debug-mode: false # Режим отладки
auto-delete-old-reports: 30 # Автоудаление старых жалоб (дни, 0 = выкл)
max-reports-per-day: 10 # Лимит жалоб от одного игрока в день

# Сообщения
messages:
prefix: "..." # Префикс всех сообщений
only-players: "..." # Команда только для игроков
# ... и другие сообщения

# GUI интерфейс
gui:
report: # Меню подачи жалобы
title: "..."
size: 27
categories: {...}

reports: # Меню управления жалобами
title: "..."
report-item: {...}


### Настройка кулдауна

yaml
# Кулдаун в секундах
cooldown-seconds: 60

# Примеры:
# 30 = 30 секунд (для маленьких серверов)
# 60 = 1 минута (рекомендуется)
# 120 = 2 минуты (для средних серверов)
# 300 = 5 минут (для больших серверов)


Обход кулдауна: Игроки с правом reportsystem.bypass.cooldown не ограничены кулдауном.

### Настройка автоудаления

yaml
# Автоматическое удаление старых жалоб
auto-delete-old-reports: 30 # Удалять жалобы старше 30 дней

# 0 = выключено (жалобы не удаляются автоматически)
# 7 = 1 неделя
# 30 = 1 месяц
# 90 = 3 месяца


### Настройка лимита жалоб

yaml
# Максимум жалоб от одного игрока в день
max-reports-per-day: 10

# Примеры:
# 5 = Для строгого контроля
# 10 = Рекомендуемое значение
# 20 = Для серверов с частыми нарушениями
# 0 = Без ограничений (не рекомендуется)


### Настройка сообщений

#### Префикс

yaml
messages:
prefix: "<gradient:FF0000:FF8800>[ReportSystem]</gradient> &f"


Примеры префиксов:

yaml
# Простой красный цвет
prefix: "&c[ReportSystem] &f"

# Hex цвет
prefix: "&#FF0000[ReportSystem] &f"

# Градиент (красный → оранжевый)
prefix: "<gradient:FF0000:FF8800>[ReportSystem]</gradient> &f"

# С эмодзи
prefix: "&#FFD700⚠ &e[Жалобы] &f"

# Градиент радуги
prefix: "<gradient:FF0000:00FF00>[Жалобы]</gradient> &f"

# Ваш стиль сервера
prefix: "&#00FFFF[МойСервер] &#FFD700Жалобы &f➤ "


#### Системные сообщения

yaml
messages:
only-players: "%prefix%&#FF0000Эту команду могут использовать только игроки!"
no-permission: "%prefix%&#FF0000У вас нет прав для использования этой команды!"
usage: "%prefix%&#FFD700Использование: &f/report <игрок>"


#### Сообщения о репортах

yaml
messages:
player-not-found: "%prefix%&#FF0000Игрок %player% не найден или не в сети!"
cannot-report-self: "%prefix%&#FF0000Вы не можете пожаловаться на самого себя!"
cooldown: "%prefix%&#FF8800Подождите &#FFD700%time% секунд &#FF8800перед следующей жалобой!"


#### Многострочные сообщения

yaml
messages:
report-sent: |
%prefix%&#00FF00Ваша жалоба успешно отправлена!
&#FFD700Игрок: &#FFFFFF%player%
&#FFD700ID жалобы: &#FFFFFF#%id%

staff-notification: |
%prefix%&#FF8800Новая жалоба!
&#FFD700От: &#FFFFFF%reporter%
&#FFD700На: &#FFFFFF%reported%
&#FFD700Причина: &#FFFFFF%reason%
&#FFD700ID: &#FFFFFF#%id%


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

| Плейсхолдер | Описание | Где используется |
|-------------|----------|------------------|
| %prefix% | Префикс из конфига | Все сообщения |
| %player% | Имя игрока | Сообщения о репорте |
| %reporter% | Имя подавшего жалобу | Уведомления |
| %reported% | Имя обвиняемого | Уведомления |
| %reason% | Причина жалобы | Уведомления |
| %id% | ID жалобы | Сообщения о репорте |
| %time% | Оставшееся время | Кулдаун |
| %page% | Номер страницы | GUI управления |
| %total% | Всего страниц | GUI управления |
| %status% | Статус жалобы | Описание жалобы |
| %date% | Дата создания | Описание жалобы |

---

## 🖥️ GUI интерфейс

### GUI подачи жалобы

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

yaml
gui:
report:
title: "&#FF0000Жалоба на: &#FFD700%player%"
size: 27 # Размер: 9, 18, 27, 36, 45, 54


#### Категории жалоб

Каждая категория настраивается отдельно:

yaml
gui:
report:
categories:
cheating: # Ключ категории
material: DIAMOND_SWORD # Тип предмета в GUI
slot: 10 # Позиция (0-26 для size: 27)
name: "&#FF0000⚔ Читы/Хаки" # Название категории
lore: # Описание (массив строк)
- "&#CCCCCC┃ Использование читов"
- "&#CCCCCC┃ Kill Aura, Fly, Speed"
- "&#CCCCCC┃ X-Ray, Auto-Clicker"
- ""
- "&#00FF00➤ Нажмите для жалобы"


#### Стандартные категории

| Категория | Material | Описание |
|-----------|----------|----------|
| cheating | DIAMOND_SWORD | Читы и хаки |
| chat_abuse | PAPER | Нарушения в чате |
| griefing | TNT | Гриферство и разрушения |
| bug_abuse | COMMAND_BLOCK | Использование багов |
| other | BOOK | Другие нарушения |

#### Добавление своей категории

yaml
gui:
report:
categories:
toxicity: # Новая категория
material: FIRE_CHARGE # Огненный шар
slot: 20 # Позиция в GUI
name: "&#FF00FF🔥 Токсичность" # Название
lore:
- "&#CCCCCC┃ Оскорбления игроков"
- "&#CCCCCC┃ Провокации"
- "&#CCCCCC┃ Троллинг"
- ""
- "&#00FF00➤ Нажмите для жалобы"


#### Схема расположения слотов (size: 27)

┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐
│ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │
├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│ 9 │ 10 │ 11 │ 12 │ 13 │ 14 │ 15 │ 16 │ 17 │
├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│ 18 │ 19 │ 20 │ 21 │ 22 │ 23 │ 24 │ 25 │ 26 │
└─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘


### GUI управления жалобами

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

yaml
gui:
reports:
title: "<gradient:FF0000:FF8800>Жалобы</gradient> &#FFD700- Страница %page%/%total%"


#### Настройка отображения жалобы

yaml
gui:
reports:
report-item:
material: PLAYER_HEAD # Голова игрока
name: "&#FF0000Жалоба #%id% &#FFD700- %reported%"
lore:
- "&#FFD700┃ Подал: &#FFFFFF%reporter%"
- "&#FFD700┃ На игрока: &#FFFFFF%reported%"
- "&#FFD700┃ Причина: &#FFFFFF%reason%"
- "&#FFD700┃ Статус: &#FFFFFF%status%"
- "&#FFD700┃ Дата: &#FFFFFF%date%"
- ""
- "&#FF0000➤ ЛКМ - Удалить жалобу"
- "&#00FF00➤ ПКМ - Телепорт к игроку"


#### Навигация

- Слот 45: Предыдущая страница (стрелка)
- Слот 49: Закрыть меню (барьер)
- Слот 53: Следующая страница (стрелка)
- Слоты 0-44: Жалобы (до 45 штук на странице)

#### Взаимодействие

| Действие | Результат |
|----------|-----------|
| ЛКМ на жалобу | Удаление жалобы |
| ПКМ на жалобу | Телепортация к обвиняемому игроку |
| Клик на стрелку влево | Предыдущая страница |
| Клик на стрелку вправо | Следующая страница |
| Клик на барьер | Закрыть меню |

---

## 🎨 Работа с цветами

### Поддержка hex/RGB цветов

Плагин поддерживает hex цвета в формате &#RRGGBB для Minecraft 1.16+.

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

yaml
# Формат: &#RRGGBB
message: "&#FF0000Красный текст"


#### Таблица популярных цветов

| Название | Hex код | Пример | Где использовать |
|----------|---------|--------|------------------|
| Красный | &#FF0000 | &#FF0000████ | Ошибки, предупреждения |
| Оранжевый | &#FF8800 | &#FF8800████ | Важные сообщения |
| Жёлтый | &#FFFF00 | &#FFFF00████ | Информация |
| Лаймовый | &#00FF00 | �FF00████ | Успех, подтверждения |
| Зелёный | &#00AA00 | �AA00████ | Положительные действия |
| Аквамарин | &#00FFFF | �FFFF████ | Дополнительная информация |
| Синий | &#0000FF | �FF████ | Нейтральные сообщения |
| Фиолетовый | &#8800FF | ≠FF████ | Особые события |
| Розовый | &#FF00FF | &#FF00FF████ | Акценты |
| Золотой | &#FFD700 | &#FFD700████ | Награды, важные элементы |
| Серебряный | &#C0C0C0 | &#C0C0C0████ | Второстепенная информация |
| Белый | &#FFFFFF | &#FFFFFF████ | Основной текст |

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

yaml
# Префикс с красным цветом
prefix: "&#FF0000[ReportSystem] &f"

# Сообщение с несколькими цветами
report-sent: "&#00FF00Жалоба отправлена! &#FFD700ID: &#FFFFFF#%id%"

# Название GUI элемента
name: "&#FF0000⚔ &#FFD700Читы и хаки"

# Список с разными цветами
lore:
- "&#CCCCCC┃ Описание"
- "&#FFD700┃ Важная информация"
- "&#00FF00➤ Действие"


### Система градиентов

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

yaml
# Формат: <gradient:START_HEX:END_HEX>текст</gradient>
message: "<gradient:FF0000:00FF00>Радужный текст</gradient>"


#### Примеры градиентов

yaml
# Огненный (красный → оранжевый)
title: "<gradient:FF0000:FF8800>Огонь</gradient>"

# Водный (синий → голубой)
title: "<gradient:0000FF:00FFFF>Вода</gradient>"

# Радуга (красный → зелёный)
title: "<gradient:FF0000:00FF00>Радуга</gradient>"

# Золотой закат (оранжевый → жёлтый)
title: "<gradient:FF8800:FFFF00>Закат</gradient>"

# Ночь (фиолетовый → синий)
title: "<gradient:8800FF:0000FF>Ночь</gradient>"

# Природа (зелёный → лайм)
title: "<gradient:00AA00:00FF00>Природа</gradient>"


#### Сложные градиенты

yaml
# Градиент в префиксе
prefix: "<gradient:FF0000:FF8800>[ReportSystem]</gradient> &f"

# Многострочные градиенты
message: |
<gradient:FF0000:FF8800>Заголовок</gradient>
&#FFFFFF Обычный текст
<gradient:00FF00:00FFFF>Подзаголовок</gradient>

# Комбинирование с hex цветами
name: "<gradient:FF0000:FF8800>⚔ Читы</gradient> &#FFFFFF и хаки"


### Стандартные цветовые коды Minecraft

Плагин также поддерживает стандартные коды &:

| Код | Цвет | Пример |
|-----|------|--------|
| &0 | Чёрный | &0████ |
| &1 | Тёмно-синий | &1████ |
| &2 | Тёмно-зелёный | &2████ |
| &3 | Тёмно-голубой | &3████ |
| &4 | Тёмно-красный | &4████ |
| &5 | Тёмно-фиолетовый | &5████ |
| &6 | Золотой | &6████ |
| &7 | Серый | &7████ |
| &8 | Тёмно-серый | &8████ |
| &9 | Синий | &9████ |
| &a | Зелёный | &a████ |
| &b | Голубой | &b████ |
| &c | Красный | &c████ |
| &d | Светло-фиолетовый | &d████ |
| &e | Жёлтый | &e████ |
| &f | Белый | &f████ |

### Форматирование текста

| Код | Эффект |
|-----|--------|
| &l | Жирный |
| &m | ~~Зачёркнутый~~ |
| &n | Подчёркнутый |
| &o | Курсив |
| &r | Сброс форматирования |

#### Примеры форматирования

yaml
# Жирный текст
name: "&l&#FF0000Важное сообщение"

# Курсив
lore: "&o&#CCCCCC Дополнительная информация"

# Комбинирование
name: "&l&n&#FFD700Заголовок"

# Градиент с форматированием
title: "&l<gradient:FF0000:FF8800>ReportSystem</gradient>"


---

## 📋 Система жалоб

### Структура жалобы

Каждая жалоба содержит следующую информацию:

java
Report {
int id; // Уникальный ID
String reporter; // Имя подавшего жалобу
UUID reporterUUID; // UUID подавшего жалобу
String reported; // Имя обвиняемого
UUID reportedUUID; // UUID обвиняемого
String reason; // Причина (категория)
long timestamp; // Метка времени создания
ReportStatus status; // Статус жалобы
}


### Статусы жалоб

| Статус | Описание | Когда используется |
|--------|----------|-------------------|
| PENDING | Ожидает | Новая жалоба, не проверена |
| REVIEWED | Проверен | Жалоба рассмотрена модератором |
| RESOLVED | Решен | Принято решение, действия выполнены |
| DISMISSED | Отклонен | Жалоба признана необоснованной |

### Файл хранения (reports.yml)

yaml
reports:
1:
reporter: "Steve"
reporter-uuid: "069a79f4-44e9-4726-a5be-fca90e38aaf5"
reported: "Alex"
reported-uuid: "8667ba71-b85a-4004-af54-457a9734eed7"
reason: "cheating"
timestamp: 1730691234567
status: "PENDING"
2:
reporter: "Player1"
reporter-uuid: "069a79f4-44e9-4726-a5be-fca90e38aaf5"
reported: "Player2"
reported-uuid: "8667ba71-b85a-4004-af54-457a9734eed7"
reason: "chat_abuse"
timestamp: 1730691345678
status: "REVIEWED"


### Жизненный цикл жалобы

1. Игрок подаёт жалобу

2. Жалоба сохраняется со статусом PENDING

3. Администрация получает уведомление

4. Модератор просматривает жалобу в /reports

5. Модератор может:
- Телепортироваться к игроку (ПКМ)
- Удалить жалобу (ЛКМ)

6. Жалоба удаляется из системы


### Автоматическое управление

#### Автоудаление старых жалоб

yaml
# В config.yml
auto-delete-old-reports: 30 # Удалять жалобы старше 30 дней


При каждом запуске сервера плагин проверяет дату создания жалоб и удаляет устаревшие.

#### Лимит жалоб в день

yaml
# В config.yml
max-reports-per-day: 10


Плагин отслеживает количество жалоб от каждого игрока за последние 24 часа.

### Уведомления

Когда создаётся новая жалоба, все онлайн игроки с правом reportsystem.notify получают уведомление:

[ReportSystem] Новая жалоба!
От: Steve
На: Alex
Причина: cheating
ID: #1


## 📜 Лицензия

Этот плагин распространяется под лицензией MIT.

Вы можете:
- ✅ Использовать в коммерческих проектах
- ✅ Модифицировать код
- ✅ Распространять
- ✅ Использовать в частных проектах

При условии:
- 📄 Сохранение копирайта и лицензии
- 📄 Указание изменений

---

Версия документации: 1.0.0
Дата обновления: 4 ноября 2025
Автор: animesao

---

Спасибо за использование ReportSystem! 🎮