Color API

Color API отвечает за единое форматирование цветного текста во всех пользовательских каналах плагина.

1. Зачем нужен отдельный Color API

Если форматирование разбросано по проекту:

• часть сообщений цветная, часть нет;
• разные модули используют разные правила;
• сложно менять визуальный стиль глобально.

ColorUtil решает это централизованно.

2. Контракт модуля

public interface ColorUtil {
    String formatMessage(String message);
}

Базовая реализация — ColorUtilImpl.

3. Поддерживаемые форматы

• & коды (&a, &7, &c, ...)
• HEX в формате &#RRGGBB
• комбинированные строки

Пример:

String text = NextLib.c.formatMessage("&7Баланс: &#00ff99$1000");

4. Внутренний алгоритм

ColorUtilImpl делает:

1. null-safe возврат пустой строки,
2. поиск HEX токенов regex-ом,
3. конвертацию HEX в Bukkit-compatible color,
4. обработку & кодов.

Результат: единый итоговый текст для Minecraft UI.

5. Где использовать

• сообщения в чат;
• названия и lore предметов;
• заголовки GUI;
• тексты ошибок/подсказок команды;
• уведомления о квестах/наградах.

6. Где не использовать

• machine logs;
• DB keys/data;
• PDC значения;
• технические метрики.

Цвет — это presentation слой, не domain data.

7. Интеграция с Item API

ItemStack item = new ItemBuilder(Material.DIAMOND)
    .setName("&bНаграда")
    .setLore(List.of("&7Редкость: &#00bcd4Epic"))
    .build();

ItemBuilder использует ColorUtil и сохраняет единый стиль.

8. Интеграция с GUI API

В YAML цвета используются в title, name, lore.

title: "&8Магазин"
items:
  buy:
    name: "&#00ff99Купить"

9. Интеграция с i18n

Лучший паттерн:

• в i18n хранить цветовые маркеры,
• перед отправкой игроку прогонять через formatMessage.

String raw = i18n.message(locale, "shop.buy.success");
player.sendMessage(colorUtil.formatMessage(raw));

10. Частые ошибки

Цвет не применился

Причины:

• строка ушла в обход форматтера;
• неверный HEX синтаксис (#ffffff вместо &#ffffff);
• текст уже преобразован и обработан повторно в некорректном месте.

Неожиданные пустые сообщения

null безопасно превращается в "". Если это нежелательно, логируйте source null на уровне сервиса.

11. Рекомендации стиля

• определить palette-гайд для проекта (info/success/warn/error);
• не злоупотреблять яркими цветами в каждом сообщении;
• использовать consistent шаблоны префиксов (&8[&bMyPlugin&8]).

12. Кастомный форматтер

Если нужны особые правила (например mini-message совместимость), можно сделать собственную реализацию ColorUtil.

public final class CustomColorUtil implements ColorUtil {
    @Override
    public String formatMessage(String message) {
        // custom logic
        return message;
    }
}

Затем внедрять его в builder/services.

13. Антипаттерны

• встраивать бизнес-идентификаторы в цветной текст;
• форматировать строку по 3-4 раза подряд;
• смешивать user-facing и admin-debug текст без разных стилей.

14. FAQ

Можно ли отключить цвета для консоли?

Да. Обычно делают отдельный formatter для console output.

Можно ли использовать HEX во всех версиях сервера?

Зависит от версии и поддержки клиентом/сервером. Для старых окружений лучше иметь fallback в & кодах.

Color API — небольшой, но важный слой, который отвечает за профессиональный и единообразный UX текста по всему плагину.