MC Matrix Bridge

Minecraft Matrix Bridge (Forge/NeoForge, только для сервера)

Связывает чат между сервером Minecraft и одной комнатой Matrix (только без шифрования).

Возможности

• MC → Matrix: пересылает чат игроков в комнату Matrix.
• Matrix → MC: пересылает сообщения m.text из комнаты Matrix в чат сервера Minecraft.
• Только для сервера: ванильные клиенты могут подключаться без установки чего-либо (клиентский мод не нужен).
• Состояние синхронизации хранится в сохранении мира (предотвращает спам повторами при перезапуске).
• Уведомление «Matrix room connected: …» локализуется на стороне сервера в зависимости от языка клиента каждого игрока (сейчас включает en_us и zh_cn).
• Если бота пригласили в настроенную комнату, но он ещё не присоединился, он автоматически примет приглашение и присоединится при запуске.
• Event Taps: динамическая подписка на события Forge/NeoForge и пересылка их в Matrix для отладки/мониторинга.

Требования

• Java 17 (Forge 1.18–1.20), Java 21 (Forge/NeoForge 1.21.x) или Java 25 (Forge/NeoForge 26.1)

• Сервер Minecraft Forge/NeoForge, соответствующий версиям. Я вручную тестирую только на популярных минорных версиях, и надеюсь, что на других минорных версиях оно тоже работает.

  • 1.18.2
  • 1.19.2
  • 1.20.1
  • 1.21.1
  • 26.1
• Комната Matrix должна быть без шифрования (без E2EE)

Установка

1. Скачай jar или собери его локально с помощью ./scripts/build_dist.sh (все поддерживаемые версии) или ./scripts/build_dist_26.sh (только 26.x). Собранные jar-файлы попадают в dist/.
2. Положи jar в папку mods/ твоего сервера Forge/NeoForge (выбери jar, соответствующий твоему загрузчику + основной версии Minecraft).
3. Запусти сервер один раз, чтобы сгенерировать конфиг.

Сборка всех версий (создаёт dist/)

Чтобы собрать jar для всех поддерживаемых версий Minecraft и сложить их в dist/:

• ./scripts/build_dist.sh

dist/ включает jar для Forge 1.18.x–1.21.x и 26.x, а также jar для NeoForge 1.21.x и 26.x.

Сборка только линейки 26.x

Проекты 26.x используют отдельный wrapper Gradle 9 и условно включаются через settings.gradle.

• Собрать и сложить оба jar 26.x в dist/: ./scripts/build_dist_26.sh
• Собрать только Forge 26: ./gradlew-26 -Pomx_modern_26=true :forge-26:build
• Собрать только NeoForge 26: ./gradlew-26 -Pomx_modern_26=true :neoforge-26:build
• В Windows используй gradlew-26.bat вместо ./gradlew-26

./scripts/build_dist_26.sh создаёт:

• `dist/minecraftmatrixbridge-forge-26.x-.jar`
• `dist/minecraftmatrixbridge-neoforge-26.x-.jar`
• dist/SHA256SUMS.txt

Конфигурация

Отредактируй config/minecraftmatrixbridge.toml:

• matrix.homeserver (обязательно), например https://matrix.example.com
• matrix.roomId (обязательно) — ID комнаты !abcdef:example.com или алиас комнаты #myroom:example.com (комната не должна быть зашифрована)
• matrix.accessToken (обязательно, либо используй переменную окружения MATRIX_ACCESS_TOKEN)

Настройки моста

• bridge.enableMcToMatrix (по умолчанию true) — Пересылать чат MC в Matrix
• bridge.enableMatrixToMc (по умолчанию true) — Пересылать сообщения Matrix в MC
• bridge.announceConnected (по умолчанию true) — Объявлять Matrix room connected: {roomIdOrAlias} при запуске моста
• bridge.enableJoinLeaveToMatrix (по умолчанию false) — Отправлять {player} joined/left the game в Matrix
• bridge.enableServerLifecycleToMatrix (по умолчанию false) — Отправлять Server started/stopping в Matrix
• bridge.mcToMatrixPrefix (по умолчанию [MC] ) — Префикс для сообщений MC в Matrix
• bridge.matrixToMcPrefix (по умолчанию [Matrix] ) — Префикс для сообщений Matrix в MC
• bridge.matrixBotPrefix (по умолчанию !mc) — Префикс команд бота Matrix; сообщения, начинающиеся с этого префикса, считаются командами бота и не пересылаются в чат Minecraft
• bridge.syncTimeoutMs (по умолчанию 30000) — Тайм-аут синхронизации Matrix в миллисекундах
• bridge.timelineLimit (по умолчанию 20) — Максимум событий ленты за одну синхронизацию
• bridge.maxQueueSize (по умолчанию 1000) — Максимальный размер очереди исходящих сообщений
• bridge.dedupSize (по умолчанию 512) — Размер кэша дедупликации событий

Настройки перехвата событий

• bridge.enableEventTaps (по умолчанию true) — Полностью включает или отключает функцию перехвата событий. При отключении индексация событий при запуске не выполняется.
• bridge.maxActiveEventTaps (по умолчанию 10) — Максимум одновременных подписок на события
• bridge.defaultEventThrottleMs (по умолчанию 1000) — Минимальный интервал между пересылаемыми событиями (защита от спама)
• bridge.eventCommandMinPowerLevel (по умолчанию 50) — Минимальный уровень прав в Matrix для использования команд событий из Matrix (0=обычный пользователь, 50=модератор, 100=админ)

Состояние сохранения мира

Состояние синхронизации хранится по пути:

• `/data/minecraftmatrixbridge/state.json`

Команды

Команды Minecraft (только для OP)

• /matrix status — Показать статус моста
• /matrix reload — Перезагрузить конфиг моста
• /matrix test — Отправить тестовое сообщение в Matrix

Команды бота Matrix

Команды бота в комнате Matrix (требуется bridge.enableMatrixToMc=true):

• !mc help (или замените !mc на bridge.matrixBotPrefix)
• !mc list — Отвечает именами игроков онлайн; командные сообщения не пересылаются в чат Minecraft

Перехват событий (продвинутое)

Перехват событий позволяет операторам сервера подписываться на события Forge/NeoForge во время работы и пересылать их в комнату Matrix. Полезно для отладки и мониторинга.

Команды Minecraft (только для OP)

• `/matrix event on [filter] [duration]` — Включить перехват события

  • eventName: простое имя класса (например, ServerChatEvent) или полное имя класса
  • filter: необязательный фильтр по подстроке (без учёта регистра)
  • duration: once (по умолчанию), permanent или время (30s, 10m, 2h, 1d)
• `/matrix event off ` — Отключить перехват события
• /matrix event list — Список активных перехватов событий
• `/matrix event search ` — Поиск доступных событий
• /matrix event help — Показать справку

Команды бота Matrix

Те же команды доступны через Matrix (требуется bridge.enableMatrixToMc=true и bridge.enableEventTaps=true):

• `!mc event on [filter] [duration]`
• `!mc event off `
• !mc event list
• `!mc event search `
• !mc event help

Команды событий Matrix требуют от отправителя уровень прав >= bridge.eventCommandMinPowerLevel (по умолчанию 50).

Защитные функции

• Главный переключатель (enableEventTaps) — отключите полностью, чтобы пропустить индексацию событий при запуске
• Максимум 10 одновременных перехватов событий (настраивается)
• По умолчанию 1 секунда между пересылаемыми событиями
• События тика автоматически соблюдают минимальный интервал в 1 секунду
• Вывод событий обрезается до 2048 символов
• События только для клиента отклоняются на выделенных серверах

Примеры

# Отслеживать все события чата (сработает один раз)
/matrix event on ServerChatEvent

# Отслеживать вход игроков в течение 10 минут
/matrix event on PlayerLoggedInEvent "" 10m

# Отслеживать разрушение блоков со словом "diamond" в данных события, постоянно
/matrix event on BlockEvent diamond permanent

# Из Matrix
!mc event on ServerChatEvent
!mc event list
!mc event off ServerChatEvent

Благодарности

Я ценю отличные мод-проекты (например, Matrix Bridge), которые вдохновили меня на создание этого проекта.

Лицензия

Мод распространяется под лицензией AGPL-3.0.