Other
ТЗ Colombino Chat
ColombinoChat — ТЗ
Плагин управления чатами/PM/упоминаниями для сети Colombino (Paper + Velocity). Цель — единая система чатов с MiniMessage, PlaceholderAPI, антиспамом, логированием и сетевым хранением данных.
0) Техническая информация
-
Название плагина:
ColombinoChat -
Поддерживаемые версии Paper:
1.20.4+ -
Платформа:
Paper + Velocity -
Сборка:
Uber-Jar(общий артефакт) или один репозиторий с двумя модулями:-
colombinochat-paper -
colombinochat-velocity
-
1) Гайдлайны
1.1 YAML
-
Формат путей:
example-path-to-something -
Все пользовательские строки (уведомления/ошибки/подсказки) — в
messages.ymlи поддерживают MiniMessage.
1.2 Git / коммиты
-
Conventional Commits по Angular (без scope): https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit-message-header
-
Пример:
feat: add mentions cooldown
1.3 Стек библиотек
-
CommandAPI не использовать.
-
Выбор библиотек (конфиг/БД/миграции) согласовать до старта, но без избыточных зависимостей.
2) Термины
-
Scope (уровень чата): область видимости сообщения.
-
Network Global: межсерверный чат по сети Velocity.
-
Server Global: чат внутри одного Paper-сервера.
-
World: чат внутри одного мира (World) на Paper.
-
Plot: чат внутри плота PlotSquared (использовать встроенный Plot chat PlotSquared или интеграцию).
3) Архитектура и зоны ответственности
3.1 Velocity (прокси)
Отвечает за:
-
Network Global (межсерверный чат)
-
Cross-server PM (
/pm,/reply) -
Синхронизированный PM ignore (персистентно)
-
Хранение/синхронизацию данных через сетевую БД PostgreSQL
-
Логи: Network Global, PM, blocked
3.2 Paper (бекенд)
Отвечает за:
-
Server/World/Plot отображение (рендер в чат)
-
Форматирование (Adventure/MiniMessage) и PAPI
-
Валидацию/антиспам
-
Mentions + звук + кулдауны
-
Логи Server/World/Plot и blocked
4) Хранение данных (обязательное)
4.1 Общее правило
Все данные, требующие хранения и/или синхронизации в сети, должны храниться в PostgreSQL.
4.2 Что хранить в БД (минимум)
-
UUID игрока → active-scope / active-channel (если включено сохранение)
-
PM ignore-листы (UUID → UUID)
-
Оффлайн-упоминания (notifications) с TTL и лимитами
4.3 Идентификаторы
-
Везде использовать UUID (ник — только для отображения).
4.4 БД-слой
-
Пул соединений (например HikariCP) — допускается/рекомендуется.
-
Миграции (Flyway/Liquibase или собственный механизм) — согласовать до начала реализации.
5) Уровни чата (Scopes)
5.1 Обязательные scopes
-
Network Global — межсерверный (Velocity)
-
Server Global — внутри Paper
-
World — внутри текущего мира
-
Plot — внутри текущего плота (PlotSquared)
5.2 Поведение Plot scope
Если игрок не находится на плоту:
-
A) блокировать отправку + уведомление отправителю
или -
B) fallback на
WorldилиServer(настраивается)
6) Переключение чатов и триггеры
6.1 Активный чат (state)
-
У игрока есть
active-scope(илиactive-channel-id). -
Настройки:
-
дефолтный scope при входе
-
сохранять ли active-scope в БД (при релоге)
-
синхронизировать ли active-scope в сети (при смене сервера в Velocity)
-
6.2 Команды переключения
Минимальный набор:
-
/chat network -
/chat server -
/chat world -
/chat plot
Алиасы настраиваемые (пример): /gc, /sc, /wc, /pc.
Команды:
-
переключают активный scope
-
возвращают подтверждение (MM)
6.3 Триггеры в сообщениях (send-only / switch-and-send)
Примеры:
-
@network <сообщение> -
@server <сообщение> -
@world <сообщение> -
@plot <сообщение>
Требования:
-
возможность задавать любые алиасы тегов/префиксов для каждого scope
-
режимы:
-
send-only(без смены active-scope) -
switch-and-send(сменить active-scope и отправить)
-
Допускается, что изменение алиасов команд/тегов может не поддерживать hot-reload.
6.4 Приоритет обработки
-
Команда (если используется команда отправки)
-
Триггер/префикс в сообщении
-
Активный scope игрока
7) Форматирование сообщений
7.1 MiniMessage в конфигурации
Во всех текстовых полях с форматированием / hover / click — MiniMessage.
7.2 Плейсхолдеры (встроенные)
-
<username>— ник отправителя -
<message>— сообщение -
<timestamp>— Unix timestamp (host time)
Дополнительно:
-
(Network)
<source_server_id> -
(Network)
<source_server_name>(маппинг ID→DisplayName на стороне Paper) -
(World)
<world> -
(Plot)
<plot_id>(если доступно)
7.3 PlaceholderAPI
-
Поддержка PAPI плейсхолдеров в местах, где это имеет смысл
-
Парсинг PAPI относительно игрока-отправителя
8) MiniMessage в сообщениях игроков и ссылки
8.1 MM в сообщении игрока
-
MM парсится только при permission:
-
colombinochat.message.minimessage
-
-
Без permission — plain text (без MM парсинга)
8.2 Автокликабельные ссылки (linkify)
-
Навешивать ClickEvent средствами Adventure.
-
Парсинг ссылок только при permission:
-
colombinochat.message.links
-
Требования:
-
при отсутствии
http(s)://добавлятьhttps://(настраиваемо) -
не ограничивать современные TLD (не использовать 2–4 символа)
-
опционально: whitelist/blacklist доменов
9) Система упоминаний (Mentions)
9.1 Упоминания
-
Тег по никнейму (например
@Nickname), паттерн настраиваем -
Подсветка упоминания задаётся отдельной настройкой (MiniMessage)
9.2 Звук и кулдаун
-
При упоминании игроку воспроизводится звук (настраиваемо)
-
Кулдаун на получателя (ms), чтобы исключить спам звуком
9.3 Оффлайн-упоминания (Notifications)
Если игрок упомянут, но оффлайн — создать уведомление:
-
доставить при следующем входе
-
при входе показать "Пока тебя не было: N упоминаний" и/или подсказку команды
Команды:
-
/mentions— список уведомлений -
/mentions clear— очистить
Требования:
-
Персистентно хранить в PostgreSQL
-
TTL (например 7 дней) и лимит на игрока (например 50)
9.4 Автокомплит
-
Комплит никнеймов онлайн игроков сети (Velocity) — по возможности
10) Cross-server PM (Личные сообщения)
Команды:
-
/pm <игрок> <сообщение>— отправить PM -
/reply <сообщение>(/r) — ответ последнему собеседнику -
/pmignore <игрок>— добавить в игнор -
/pmignore remove <игрок>— убрать из игнора -
/pmignore list— список игнорируемых
Требования:
-
Автокомплит никнеймов онлайн игроков сети (Velocity)
-
Ignore хранится персистентно в PostgreSQL
-
Отдельные форматы для входящих/исходящих PM (MiniMessage)
Опционально:
-
звуки на отправку/получение PM (настраиваемо на Paper)
-
SocialSpy:
-
/socialspy(toggle) -
permission
colombinochat.socialspy
-
11) Валидация сообщений (Regex)
Конфиг (пример):
validation:
enabled: true
regex: "^[!\"@№;%:?*()_=#$^&\\/\\-—+`~;'<>\u005B\u005D{}|,.a-zA-Zа-яА-ЯёЁҐґЄєЇї0-9\\s]+$"
Требования:
-
Валидация применяется к:
-
server/world/plot
-
network (до отправки на прокси)
-
pm
-
-
При блокировке — уведомление отправителю (MM)
Permission bypass:
-
colombinochat.validation.bypass
12) Фильтрация однотипных сообщений (Levenshtein Similarity)
Цель: блокировать спам “почти одинаковыми” сообщениями.
Настройки:
-
similarity.enabled -
similarity.threshold-percent(0..100) -
similarity.window-seconds(например 60) -
similarity.max-message-length(лимит на расчёт)
Определение:
-
сравнивать текущее сообщение с последним сообщением игрока в пределах
window-seconds -
similarity = 1 - (levenshtein / max(len1, len2)) -
блокировать, если
similarity*100 >= threshold-percent
Нормализация (настраиваемо):
-
lower-case
-
trim
-
collapse spaces
-
optional: remove punctuation
Permission bypass:
-
colombinochat.similarity.bypass
13) Логирование
13.1 Требование по формату и именованию
Формат и ротация логов должны соответствовать формату логов сервера. Хороший пример — дата в имени файла в ISO-формате (YYYY-MM-DD).
13.2 Что логировать
-
Все сообщения чатов
-
Все PM
-
Сообщения, заблокированные:
-
validation
-
similarity
-
permissions/прочие фильтры
-
13.3 Где логировать
-
Server/World/Plot — на Paper
-
Network Global — на Velocity
-
PM — на Velocity
13.4 Минимальная структура
Должны быть минимум два потока:
-
разрешённые сообщения
-
заблокированные сообщения
Пример (точное имя/папка — по стандарту сервера):
-
logs/colombinochat/2026-02-22-chat.log -
logs/colombinochat/2026-02-22-chat-blocked.log
14) Permissions (минимум)
Чаты:
-
colombinochat.chat.network -
colombinochat.chat.server -
colombinochat.chat.world -
colombinochat.chat.plot
PM:
-
colombinochat.pm.send -
colombinochat.pm.reply -
colombinochat.pm.ignore
Сообщения:
-
colombinochat.message.minimessage -
colombinochat.message.links
Bypass:
-
colombinochat.validation.bypass -
colombinochat.similarity.bypass
Mentions (опционально):
-
colombinochat.mentions.bypass
15) Hot Reload
Команда:
-
/colombinochat reload
Требования:
-
reload перезагружает: форматы, messages, validation, similarity, mentions
-
предусмотреть отдельную подкоманду для работы с БД:
-
/colombinochat reload db— переподключение/проверка соединения, обновление кэшей (если используются)
-
-
алиасы команд/регистрация новых команд может требовать рестарт (допускается)
16) Acceptance Criteria (готовность)
-
Работают 4 scope: network/server/world/plot (форматы + триггеры)
-
Активный scope переключается и сохраняется согласно настройкам (если включено)
-
PM/Reply/Ignore работают по сети Velocity и используют PostgreSQL
-
Mentions работают со звуком и кулдауном; оффлайн-упоминания доставляются при входе и хранятся в PostgreSQL
-
Validation и Similarity корректно блокируют сообщения + уведомляют отправителя
-
Linkify работает только при permission
-
Логи пишутся на корректной стороне (paper/velocity), имена/даты соответствуют формату логов сервера, есть blocked лог
Опциональные интеграции / отложено
A) Реплейсер строк (Text Replacer) — опционально
Фича может быть добавлена позже при необходимости.
Пример конфига:
replacer:
enabled: true
mappings:
":doge:": "☺"
":lol:": "☻"
B) Discord Bridge — отложено
Discord bridge исключён из текущего объёма работ, т.к. требует интеграции с системой верификации и наличия у неё API.
Вернуться к задаче после утверждения:
-
модели верификации
-
API/протокола взаимодействия бота и прокси
-
требований по безопасности и анти-эхо