🇬🇧 English

About

ChatManager-Core is a core library for a complete overhaul of Minecraft's chat handling. The mod does not add a ready-made visual interface on its own — instead, it intercepts all vanilla chat processing at the network and client level and replaces it with its own architecture: channels, events, message parsing, and an extensible API.

How it works technically

Mixins intercept the handlePlayerChat and handleSystemChat packets, as well as locally added client-side messages. Standard processing of these packets is fully cancelled — instead, every message is wrapped into a unified Message model (with types: player, system, client, error, mentioned, animated, custom) and dispatched through an event bus built on MegaEvents, an open-source event library by Ferra13671. Keyboard, mouse, and scroll input are also intercepted, which is required so that channel windows can be moved, resized, and scrolled independently of the standard game UI.

Channel system

• Messages are routed into configurable channels based on regex patterns — for example, you can split trade chat, clan chat, or system messages into separate windows.
• Each channel keeps its own message history with a configurable size limit.
• Channels can be shown or hidden through settings.
• A fully programmatic API is available for registering custom message parsers (ChatMessageParser) and handlers (MessageHandler) if you're building your own mod on top of this core.

Message processing and quality-of-life features

• Built-in math engine (={...}) — evaluate mathematical expressions directly in the chat input box with support for basic operators, trigonometry, factorials, constants, and custom constants and functions from the config. Features real-time preview (validity color highlighting), Brigadier autocomplete, and instant formula-to-result replacement via the TAB key. The config offers a radians mode, number format, and a custom expression prefix.
• Input history (Undo / Redo) — full undo and redo stacks (undoStack and redoStack) enabling smooth Ctrl+Z and Ctrl+Y hotkey functionality in chat.
• Message chunking (ChatQueueManager) — automatic bypass of the standard vanilla 256-character limit: long messages are neatly split into chunks and sent sequentially with a configurable delay.
• Repeat collapsing — if an identical message arrives multiple times in a row within a short window, it isn't duplicated line by line; instead it's collapsed into a single line with a repeat counter, e.g. (x5).
• Mention detection — if your nickname appears in a message, it's flagged with a dedicated message type and accompanied by a sound notification.
• Chat aliases — configure a list of text replacements that are automatically substituted when sending a message (e.g. shortcuts for frequently used phrases). Aliases can optionally be applied to commands as well, not just regular messages.
• Macros — a separate system of named text snippets with an enable/disable toggle and a timer, intended for automating repetitive chat actions.
• Password hiding — arguments of /login (/l), /register (/reg) and /changepassword (/changepass) are masked right in the input box.

🎙️ Voice input (Speech-to-Text)

Offline speech recognition powered by Vosk: microphone audio is processed locally on your computer and is never sent to the cloud.

• 30+ languages and many models are supported, from compact (~30–50 MB) to large (up to several GB). A small Russian model is used by default.
• Models are downloaded on demand and stored in the mod's config folder. A loaded model is cached in memory and can be released at any time.
• A mic indicator shows loading, listening, errors and real-time input volume. Indicator colors are configurable in the voice config.
• Events for developers: model missing, model download (success/failure), microphone not supported, partial and final recognition results.

🎞️ Chat GIFs

Animated GIFs right in messages: search, trending, download, conversion to a custom .mcanim format, and caching. Use the :slug: syntax or a numeric ID; such messages get the dedicated ANIMATED type.

GIF search is powered by Klipy. To avoid exposing the API key inside the mod, requests don't go directly to Klipy — they go through a Cloudflare Workers proxy (https://core.chatmanager.workers.dev/gifs/), which forwards them to Klipy. A request contains the search phrase and a client identifier (customer_id), which is a SHA-256 hash generated from the player's nickname and UUID.

Conversion to .mcanim is done by a native library, which is currently available for Windows x64 only.

Game events

• PlayerDeathEvent — player death with coordinates (X/Y/Z); handy for, say, a message with your death coordinates.
• SendPosEvent — the player's position at the moment a chat message is sent.

AI text styling

Built-in integration with the Groq API (an external cloud service for LLM inference). Users can define several named "styles," each with its own model, system prompt, and response length limit, and use them to automatically rephrase text before sending it. This feature requires the user's own API key, obtained independently from Groq's website and entered into the config.

Webhooks — forwarding messages to external services

The mod can send chat messages to an external HTTP address via a POST request — useful, for example, for forwarding in-game chat to a Discord channel through a webhook. Configuration is two-tiered:

• Global webhook — a single default address for all messages.
• Per-channel webhook — overrides the global one for a specific channel; if enabled, it's used instead of the global webhook.
• Each webhook can independently choose the payload format: plain unformatted text, or a serialized Minecraft text component (with colors and styling, as JSON).
• Any channel can be fully excluded from forwarding, regardless of global settings.

This feature is disabled by default and requires the user to manually specify a destination address in the config file — without that, no message is ever sent anywhere.

Configuration and data storage

Settings are powered by Cloth Config and stored in human-readable files (Jankson / JSON5) in config/ChatManager-Core/, automatically generated with default values on first launch. A custom file logger writes a dedicated log file for diagnosing mod behavior.

For other mod developers

The core is built entirely around the open MegaEvents event bus (by Ferra13671): message received, message added to a channel, message stacked, player mentioned, channel visibility changed, keyboard/mouse input, client ticks, player death, voice input events — any of these events can be subscribed to from your own mod to build a custom visual layer on top of the core, without having to reimplement chat interception logic from scratch.

Version-dependent Minecraft code is hidden behind the utils.compat abstraction layer. Providers (ComponentSerializerProvider, ClickEventProvider, HoverEventProvider, ScreenProvider, GameProfileProvider, PacketCompatProvider, GraphicsProvider) give you static entry points that make writing code a little bit more convenient: write it once without caring how a given thing looks in 1.21.4 vs 26.2. Shared keyboard, mouse and added-message handlers live in utils.compat.handlers.

⚠️ Important before installing

• This is a core library with no built-in visual interface. On its own, the mod cancels vanilla chat processing but does not draw an alternative interface — without an add-on mod that implements rendering, chat will not visually appear on screen, even though it's still being processed internally.
• The webhook and AI styling features can send message text to external servers/services (a user-specified HTTP address and/or the Groq API, respectively). Both features are disabled by default and require explicit manual configuration (address, API key) to activate — without that, no data is sent anywhere.
• GIFs talk to an external service: requests go to the core.chatmanager.workers.dev proxy and then on to Klipy (the search phrase and an identifier built from the player's name and UUID).
• Voice input downloads the Vosk library (Maven Central) and the selected language model on first use. Speech recognition itself runs locally.
• Each jar fits a single Minecraft version and a single loader — pick the file for your version.

Compatibility

Parameter	Value
Minecraft	1.21.4 (Java 21+), 26.2 (Java 25+)
Loaders	Fabric, NeoForge
Dependencies	Cloth Config
Build format	1 jar = 1 Minecraft version + 1 loader

💡 Inspiration

Ideas for some of the features came from these mods — thanks to their authors:

• Chat Plus
• Chat Calc KT
• Advanced Chat Core (Reboot)
• Translation Mod

---

🇷🇺 Русский

О проекте

ChatManager-Core — это библиотека-ядро для полной переработки чата в Minecraft. Мод не добавляет готовый визуальный интерфейс сам по себе, а перехватывает всю обработку ванильного чата на уровне сети и клиента и заменяет её собственной архитектурой: каналами, событиями, парсингом сообщений и расширяемым API.

Как это работает технически

Через миксины перехватываются пакеты handlePlayerChat и handleSystemChat, а также добавление локальных клиентских сообщений. Стандартная обработка этих пакетов полностью отменяется — вместо неё каждое сообщение оборачивается в единую модель Message (с типами: игрок, система, клиент, ошибка, упоминание, анимированное, кастомное) и рассылается через событийную шину на базе MegaEvents — открытой библиотеки событий за авторством Ferra13671. Также перехватываются события клавиатуры, мыши и скролла — это нужно, чтобы окна каналов можно было двигать, изменять размер и прокручивать независимо от стандартного игрового интерфейса.

Система каналов

• Сообщения распределяются по настраиваемым каналам на основе regex-паттернов — например, можно вынести торговый чат, клановый чат или системные сообщения в отдельные окна.
• У каждого канала своя история сообщений с ограничением по количеству хранимых записей.
• Каналы можно скрывать/показывать, менять их видимость через настройки.
• Полностью программный API для регистрации собственных парсеров сообщений (ChatMessageParser) и обработчиков (MessageHandler), если вы разрабатываете свой мод поверх этого ядра.

Обработка и удобства чата

• Встроенный математический движок (={...}) — вычисление математических выражений прямо в строке ввода с поддержкой базовых операторов, тригонометрии, факториалов, констант, а также кастомных констант и функций из конфига. Сопровождается реал-тайм превью (зелёная/красная подсветка валидности), умным автокомплитом (Brigadier) и возможностью мгновенной замены формулы на результат по клавише TAB. В конфиге доступны режим радиан, формат чисел и свой префикс выражений.
• История ввода (Undo / Redo) — полноценные стеки отмены и повтора (undoStack и redoStack) для удобной работы горячих клавиш Ctrl+Z и Ctrl+Y прямо в чате.
• Чанкование сообщений (ChatQueueManager) — автоматический обход стандартного ванильного лимита в 256 символов: длинные сообщения аккуратно разбиваются на части и отправляются в очередь с настраиваемой задержкой.
• Сворачивание повторов — если одинаковое сообщение приходит несколько раз подряд в течение короткого промежутка времени, оно не дублируется построчно, а сворачивается в один текст со счётчиком повторов вида (x5).
• Обнаружение упоминаний — если в сообщении встречается ваш никнейм, оно помечается отдельным типом и сопровождается звуковым сигналом.
• Алиасы чата — можно настроить список текстовых замен, которые автоматически подставляются при отправке сообщения (например, сокращение часто используемых фраз). Опционально алиасы можно применять и к командам, а не только к обычным сообщениям.
• Макросы — отдельная система именованных текстовых заготовок с возможностью включения/выключения и таймером, для автоматизации повторяющихся действий в чате.
• Скрытие паролей — аргументы команд /login (/l), /register (/reg) и /changepassword (/changepass) маскируются прямо в строке ввода.

🎙️ Голосовой ввод (Speech-to-Text)

Офлайн-распознавание речи на базе Vosk: звук с микрофона обрабатывается локально, на вашем компьютере, без отправки в облако.

• Поддерживается 30+ языков и множество моделей — от компактных (~30–50 МБ) до больших (до нескольких ГБ). По умолчанию используется небольшая русская модель.
• Модели скачиваются по требованию и хранятся в папке конфигов мода. Загруженная модель кэшируется в памяти, а освободить её можно в любой момент.
• Индикатор микрофона показывает загрузку, прослушивание, ошибки и уровень громкости в реальном времени. Цвета индикатора настраиваются в конфиге voice.
• Для разработчиков доступны события: модель отсутствует, загрузка модели (успех/ошибка), микрофон не поддерживается, промежуточный и итоговый результат распознавания.

🎞️ GIF в чате

Анимированные GIF прямо в сообщениях: поиск, тренды, загрузка, конвертация в собственный формат .mcanim и кэширование. Вставляются в формате :slug: или по числовому ID, а такие сообщения получают отдельный тип ANIMATED.

Поиск GIF работает через Klipy. Чтобы не раскрывать API-ключ в самом моде, запросы идут не напрямую, а через прокси на Cloudflare Workers (https://core.chatmanager.workers.dev/gifs/), который переадресует их в Klipy. В запросе передаются поисковая фраза и идентификатор клиента (customer_id), представляющий собой хэш SHA-256 из ника и UUID игрока.

Конвертация в .mcanim выполняется нативной библиотекой, и сейчас она доступна только под Windows x64.

Игровые события

• PlayerDeathEvent — смерть игрока с координатами (X/Y/Z), на нём можно построить, например, сообщение с координатами смерти.
• SendPosEvent — позиция игрока в момент отправки сообщения в чат.

AI-стилизация текста

Встроена интеграция с Groq API (внешний облачный сервис для инференса языковых моделей). Пользователь может создать несколько именованных "стилей" — каждый со своей моделью, системным промптом и ограничением на длину ответа — и использовать их для автоматической обработки/переформулирования текста перед отправкой. Для работы этой функции нужен собственный API-ключ, который пользователь получает самостоятельно на сайте Groq и вписывает в конфиг.

Вебхуки — пересылка сообщений на внешние сервисы

Мод умеет отправлять сообщения чата на внешний HTTP-адрес методом POST — это можно использовать, например, для пересылки игрового чата в Discord-канал через вебхук. Настройка двухуровневая:

• Глобальный вебхук — единый адрес для всех сообщений по умолчанию.
• Локальный вебхук канала — переопределяет глобальный для конкретного канала; если он включён, используется вместо глобального.
• Для каждого вебхука отдельно можно выбрать формат передаваемых данных: обычный текст без форматирования или сериализованный Minecraft-компонент (с цветами и стилями в виде JSON).
• Любой канал можно полностью исключить из пересылки, независимо от глобальных настроек.

Функция выключена по умолчанию и требует, чтобы пользователь сам вручную указал адрес назначения в конфигурационном файле — без этого ни одно сообщение никуда не отправляется.

Конфигурация и хранение данных

Настройки работают на базе Cloth Config и хранятся в человекочитаемых файлах (Jankson / JSON5) в папке config/ChatManager-Core/. Они генерируются автоматически со значениями по умолчанию при первом запуске. Есть собственный файловый логгер, пишущий отдельный лог-файл для диагностики работы мода.

Для разработчиков других модов

Ядро полностью построено вокруг открытой событийной шины MegaEvents (автор — Ferra13671): получение сообщения, добавление в канал, стак повторов, упоминание игрока, изменение видимости канала, ввод с клавиатуры/мыши, тики клиента, смерть игрока, события голосового ввода — на любое из этих событий можно подписаться из своего мода и построить поверх ядра собственный визуальный слой, не переписывая логику перехвата чата с нуля.

Версионно-зависимый код Minecraft скрыт за слоем абстракций utils.compat. Провайдеры (ComponentSerializerProvider, ClickEventProvider, HoverEventProvider, ScreenProvider, GameProfileProvider, PacketCompatProvider, GraphicsProvider) дают статические точки доступа, которые немного упрощают код: его можно писать один раз, не задумываясь, как та или иная вещь выглядит в 1.21.4 и в 26.2. Общие обработчики клавиатуры, мыши и добавления сообщений лежат в utils.compat.handlers.

⚠️ Важно перед установкой

• Это библиотека-ядро без собственного визуального интерфейса. Сам по себе мод отменяет стандартную обработку чата, но не рисует альтернативный интерфейс — если поставить только его без мода-надстройки, реализующего отображение, чат визуально не будет отображаться на экране, хотя технически продолжит обрабатываться.
• Функции вебхуков и AI-стилизации могут отправлять текст сообщений на внешние сервера/сервисы (пользовательский HTTP-адрес и/или Groq API соответственно). Обе функции отключены по умолчанию и требуют явной ручной настройки (адрес, API-ключ) для активации — без этого никакие данные никуда не отправляются.
• GIF обращаются к внешнему сервису: запросы уходят на прокси core.chatmanager.workers.dev и далее в Klipy (поисковая фраза и идентификатор из ника и UUID игрока).
• Голосовой ввод при первом использовании скачивает библиотеку Vosk (Maven Central) и выбранную языковую модель. Само распознавание речи происходит локально.
• Каждый jar подходит только для одной версии Minecraft и одного загрузчика — выбирайте файл под свою версию.

Совместимость

Параметр	Значение
Minecraft	1.21.4 (Java 21+), 26.2 (Java 25+)
Загрузчики	Fabric, NeoForge
Зависимости	Cloth Config
Формат сборок	1 jar = 1 версия Minecraft + 1 загрузчик

💡 Вдохновение

Идеи для части функций возникли благодаря этим модам — спасибо их авторам:

• Chat Plus
• Chat Calc KT
• Advanced Chat Core (Reboot)
• Translation Mod