LoChat/README.md

# LoChat - Advanced Chat Plugin

Мощный чат плагин для Paper/Folia серверов с градиентными никами, продвинутой модерацией и гибкой конфигурацией.

## Сборка и локальный тестовый сервер

```bash
./gradlew runServer
```

Gradle задача `runServer` ([run-paper](https://github.com/jpenilla/run-paper)) скачивает Paper 1.21.1, собирает JAR плагина и кладёт его в `run/plugins`. Первый запуск долгий из-за загрузки. Остановка через `stop` в консоли сервера.

## Основные возможности

### Чат система
- Глобальный чат - общение между всеми игроками
- Локальный чат - общение в радиусе
- Личные сообщения - PM система с ответами
- Игнорирование - блокировка нежелательных игроков
- Упоминания - @player, @everyone, @here, @role
- Hover/Click события - интерактивные сообщения
- Кастомные сообщения входа/выхода/смерти с названием оружия

### Градиентные ники и префиксы
- Кастомные градиентные цвета (до 7 цветов)
- Готовые пресеты (огонь, океан, радуга и т.д.)
- Кастомные префиксы и суффиксы
- Интеграция с LuckPerms (префиксы и суффиксы с градиентом)
- Система покупки через PlayerPoints
- Кулдауны и ограничения

### Модерация
- Мут система с историей
- Бан система с временем и причиной
- Варны (предупреждения)
- Временные и постоянные наказания
- Скрытые муты (silent)
- Готовые причины наказаний
- Эскалация наказаний

### Фильтры чата
- Фильтр мата с защитой от обхода (х->x, о->o и т.д.)
- Антиспам и антифлуд
- CAPS фильтр
- URL и IP фильтр
- Фильтр скрытых ссылок (discord.gg, bit.ly и т.д.)
- Фильтр повторяющихся символов
- Настраиваемый список запрещенных слов

### RP команды
- /me - действия от третьего лица
- /do - описание действий
- /try - попытка действия с шансом
- /roll - бросок кубика
- Настраиваемый радиус и кулдауны

### Звуковые эффекты
- Звуки для PM и упоминаний
- Звуки для мутов/размутов
- Звуки для градиентов
- Звуки для команд
- Персональные настройки звуков

### Discord интеграция
- Webhook для отправки сообщений
- События входа/выхода/смерти
- Кастомные форматы и цвета
- Аватары игроков
- Фильтрация сообщений

## Структура конфигов

```
plugins/LoChat/
├── config.yml                    # Основной конфиг (все настройки в одном месте)
├── messages.yml                  # Сообщения плагина
├── custom-commands.yml           # Кастомные команды
├── badwords.txt                  # Список запрещенных слов
│
├── config/
│   ├── appearance.yml            # Внешний вид чата (префиксы, форматы, hover)
│   ├── discord.yml               # Discord интеграция
│   ├── filters.yml               # Настройки фильтров
│   ├── messages.yml              # Дополнительные сообщения
│   ├── mute.yml                  # Настройки мутов
│   └── sounds.yml                # Звуковые эффекты
│
└── data/
    ├── mutes.yml                 # Данные мутов
    ├── bans.yml                  # Данные банов
    ├── ignores.yml               # Игнорирование
    └── gradient-data.yml         # Градиентные ники
```

## Быстрый старт

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

1. Скачайте последнюю версию из Releases
2. Поместите JAR в папку `plugins/`
3. Перезапустите сервер
4. Настройте конфиги в `plugins/LoChat/`

### Первая настройка

1. **Основной конфиг** (`config.yml`):
   - Настройте радиус локального чата
   - Включите/отключите нужные функции
   - Настройте цены на градиенты
   - Настройте фильтры

2. **Фильтр мата** (`badwords.txt`):
   - Добавьте свои запрещенные слова
   - По одному слову на строку
   - Строки с # игнорируются

3. **Внешний вид** (`config/appearance.yml`):
   - Настройте префиксы чата (GLOBAL/LOCAL)
   - Измените цвета и форматы
   - Настройте hover подсказки
   - Добавьте эмодзи

4. **Discord** (`config/discord.yml`):
   - Вставьте URL вебхука
   - Настройте форматы сообщений
   - Включите нужные события

## Сборка из исходников

```bash
# Клонировать репозиторий
git clone https://codeberg.org/loki5512344/Lochat.git
cd Lochat

# Собрать проект
./gradlew build

# Jar файл будет в build/libs/
```

## Зависимости

### Обязательные
- Java 21+
- Paper 1.21.1+ или Folia

### Опциональные
- PlaceholderAPI - для плейсхолдеров
- LuckPerms - для градиентных префиксов/суффиксов
- PlayerPoints - для покупки градиентов
- LibertyBans - синхронизация мутов
- SkinsRestorer - поддержка скинов

## Команды

### Чат команды
- `/g <сообщение>` - глобальный чат
- `/l <сообщение>` - локальный чат
- `/msg <игрок> <сообщение>` - личное сообщение
- `/reply <сообщение>` - ответить на ЛС
- `/ignore <игрок>` - игнорировать игрока
- `/unignore <игрок>` - разигнорировать
- `/ignorelist` - список игнорируемых

### Градиенты
- `/color <hex1> [hex2] ...` - установить градиент
- `/prefix <текст>` - установить префикс
- `/aprefix <команда>` - админские команды градиентов

### Модерация
- `/lmute <игрок> [время] [-s] [причина]` - замутить
- `/lunmute <игрок> [-s]` - размутить
- `/lban <игрок> [время] [причина]` - забанить
- `/lunban <игрок>` - разбанить
- `/lwarn <игрок> [причина]` - выдать варн
- `/lmutelist` - список мутов
- `/lmutehistory <игрок>` - история мутов

### RP команды
- `/me <действие>` - действие от 3-го лица
- `/do <описание>` - описание действия
- `/try <попытка>` - попытка с шансом
- `/roll [число]` - бросок кубика

### Админские
- `/lochat reload` - перезагрузить конфиг
- `/clearchat` - очистить чат
- `/chatspy` - режим шпиона
- `/announce <сообщение>` - объявление

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

### Градиентный ник
```
/color #FF0000 #00FF00 #0000FF
```
Создаст радужный градиент от красного через зеленый к синему.

### Кастомный префикс
```
/prefix [VIP]
```
Установит префикс `[VIP]` перед ником.

### Настройка системы оплаты градиентов

#### Вариант 1: Через PlayerPoints (платно)
```yaml
# config.yml
gradient:
  price-per-color: 50
  prefix-price: 500
  use-permission-instead-of-cost: false
```

#### Вариант 2: Через пермишены (бесплатно)
```yaml
# config.yml
gradient:
  price-per-color: 0
  prefix-price: 0
  use-permission-instead-of-cost: true
```

Выдайте игрокам права:
```
/lp user <игрок> permission set gradient.color true
/lp user <игрок> permission set gradient.prefix true
/lp user <игрок> permission set gradient.bypass.cost true
```

### Основные пермишены

#### Градиенты
- `gradient.color` - доступ к /color
- `gradient.prefix` - доступ к /prefix
- `gradient.bypass.cost` - бесплатное использование
- `gradient.bypass.cooldown` - обход кулдауна
- `gradient.admin` - админские команды

#### Чат
- `lochat.chat.colors` - цветные сообщения
- `lochat.chat.global` - глобальный чат
- `lochat.chat.local` - локальный чат
- `lochat.pm` - личные сообщения

#### Модерация
- `lochat.mute` - мутить игроков
- `lochat.mute.silent` - скрытые муты
- `lochat.ban` - банить игроков
- `lochat.warn` - выдавать варны

#### Обход фильтров
- `lochat.bypass.swear` - обход мат-фильтра
- `lochat.bypass.spam` - обход антиспама
- `lochat.bypass.flood` - обход антифлуда
- `lochat.bypass.caps` - обход CAPS фильтра
- `lochat.bypass.urlfilter` - обход URL фильтра
- `lochat.bypass.cooldown` - обход кулдауна

### Мут игрока
```
/lmute Player123 1h Спам в чате
```
Замутит игрока на 1 час с причиной "Спам в чате".

### Скрытый мут
```
/lmute Player123 30m -s Нарушение правил
```
Замутит игрока скрытно (другие игроки не увидят уведомление).

### Бан с причиной
```
/lban Player123 7d Читы
```
Забанит игрока на 7 дней с причиной "Читы".

## Форматы времени

- `s` - секунды (30s = 30 секунд)
- `m` - минуты (15m = 15 минут)
- `h` - часы (2h = 2 часа)
- `d` - дни (7d = 7 дней)
- `perm` или `0` - навсегда

Примеры:
- `1h30m` - 1 час 30 минут
- `7d` - 7 дней
- `perm` - навсегда

## Плейсхолдеры

### Чат
- `{player}` - ник игрока
- `{player_prefix}` - префикс игрока (LuckPerms/градиент)
- `{player_suffix}` - суффикс игрока (LuckPerms/градиент)
- `{message}` - текст сообщения
- `{emoji}` - эмодзи префикса чата
- `{prefix}` - префикс чата (GLOBAL/LOCAL)
- `{separator}` - разделитель

### Hover
- `{player}` - ник игрока
- `{world}` - мир игрока
- `{ping}` - пинг
- `{gamemode}` - режим игры
- `{health}` - здоровье
- `{food}` - голод

### Смерть
- `{player}` - ник погибшего
- `{killer}` - ник убийцы
- `{weapon}` - название оружия
- `{death_message}` - стандартное сообщение смерти

## API для разработчиков

### Получение сервисов
```java
// Получить ServiceRegistry
ServiceRegistry registry = plugin.getServiceRegistry();

// Получить сервис чата
ChatService chatService = registry.get(ChatService.class);

// Отправить глобальное сообщение
chatService.sendGlobalMessage(player, "Привет!");

// Получить сервис мутов
MuteService muteService = registry.get(MuteService.class);

// Проверить мут
if (muteService.isMuted(player.getUniqueId())) {
    // Игрок замучен
}
```

### Создание кастомного фильтра
```java
public class MyFilter implements MessageFilter {
    @Override
    public FilterResult filter(Player player, String message) {
        if (message.contains("запрещено")) {
            return FilterResult.blocked("Сообщение заблокировано");
        }
        return FilterResult.ok(message);
    }
}
```

## Известные проблемы

- Градиенты могут некорректно отображаться в старых версиях клиента (< 1.16)
- Некоторые фильтры могут блокировать легитимные сообщения (настраивается в `config/filters.yml`)

## Статистика проекта

- Версия: 1.5.5
- Строк кода: 9000+
- Конфигов: 10+
- Команд: 30+

## Вклад в проект

Мы приветствуем вклад в развитие проекта! Перед началом работы ознакомьтесь с:
- [Code of Conduct](CODE_OF_CONDUCT.md) - правила поведения в сообществе
- [Security Policy](SECURITY.md) - политика безопасности

### Как внести вклад

1. Fork репозитория
2. Создайте ветку для фичи (`git checkout -b feature/amazing-feature`)
3. Commit изменения (`git commit -m 'Add amazing feature'`)
4. Push в ветку (`git push origin feature/amazing-feature`)
5. Откройте Pull Request

### Типы вклада

- 🐛 Исправление багов
- ✨ Новые функции
- 📝 Улучшение документации
- 🎨 Улучшение UI/UX
- ⚡ Оптимизация производительности
- 🔒 Улучшение безопасности

## Лицензия

GNU General Public License v3.0 - см. файл [LICENSE](LICENSE)

Это свободное программное обеспечение. Вы можете распространять и/или модифицировать его в соответствии с условиями GNU General Public License версии 3.

## Автор

Loki Development Team
- Codeberg: @loki5512344

## Ссылки

- [Codeberg Repository](https://codeberg.org/loki5512344/Lochat)
- [Issues](https://codeberg.org/loki5512344/Lochat/issues)