Документация по функциональным возможностям платформы Minecraft

MinecraftAdapter — это адаптер для сервера Minecraft Java Edition, основанный на протоколе RCON, поддерживающий выполнение команд, отправку сообщений и слушание событий журналов.

Информация о документации

• Версия соответствующего модуля: 0.1.0
• Ответственный: ErisPulse

Основная информация

• Описание платформы: Робот-сервер Minecraft Java Edition (через удалённый RCON-консоль)
• Название адаптера: MinecraftAdapter
• Поддержка нескольких серверов: Поддерживается (по одному серверу на аккаунт, автоматическое повторное подключение при разрыве)
• Способ подключения: RCON TCP-длинное подключение (поддержка активной связи и экспоненциального повторного подключения)
• Способ аутентификации: RCON-пароль (rcon.password из server.properties)
• Слушание событий: tail-логов (по желанию, события чата/входа/выхода)
• Поддержка цепочечных модификаторов: Поддерживается .At() и другие цепочечные методы
• Совместимость с OneBot12: Только текстовые сегменты (RCON не может отправлять медиа)

Предварительная настройка сервера

server.properties:

enable-rcon=true
rcon.port=25575
rcon.password=your_rcon_password

Описание конфигурации

[MinecraftAdapter.accounts.default]
host = "127.0.0.1"             # Адрес RCON-сервера
port = 25575                   # Порт RCON
password = "your_rcon_password"
bot_id = ""                    # Оставьте пустым, по умолчанию имя аккаунта
enable_log_tail = false        # Включить прослушивание логов (события чата/входа/выхода)
log_path = "logs/latest.log"   # Путь к файлу логов
poll_interval = 1.0            # Интервал сканирования логов (секунды)
enabled = true

Описание параметров конфигурации (для каждого аккаунта):

• host / port / password: конечная точка RCON (обязательно)
• bot_id: идентификатор бота в событиях (по умолчанию имя аккаунта), также используется как group_id для широковещательных сообщений
• enable_log_tail: переключатель логов (по умолчанию отключено). При отключении адаптер работает в режиме только отправки (не генерирует события)
• log_path: путь к файлу логов. Требуется, чтобы адаптер и сервер работали на одной машине или каталог логов был смонтирован; поддерживается ротация логов (latest.log после ротации автоматически сбрасывает позицию чтения)
• poll_interval: интервал сканирования логов (секунды, минимум 0.2)

Отправка сообщений

Все методы отправки возвращают задачу (Task), ожидание которой даёт стандартный ответ (см. «Формат возвращаемых значений»).

Базовая отправка

from ErisPulse import sdk
mc = sdk.adapter.get("minecraft")

# Сообщение одному игроку (tellraw, чистый текст)
await mc.Send.To("user", "Steve").Text("Hello Steve")

# Широковещательное сообщение (say)
await mc.Send.To("server", "myserver").Text("Серверное сообщение")

Методы цепочечного модификатора

# @игрок (внутренняя вставка имени игрока в tellraw)
await mc.Send.To("server", "myserver").At("Steve").Text(" Посмотри на это")

Отправка на несколько серверов

await mc.Send.Using("server2").To("server", "s2").Text("Сообщение с второго сервера")

Поддерживаемые и неподдерживаемые сегменты сообщений

Типы целей

Стандартные API-действия (Api)

from ErisPulse import sdk
mc = sdk.adapter.get("minecraft")

# Список онлайн игроков (парсинг вывода команды list)
result = await mc.Api.get_player_list()       # {"players": ["Steve", "Alex"], "raw": "..."}

# Статус подключения
result = await mc.Api.get_status()            # {"status": "ok", "connected": true}

# Идентификация сервера
result = await mc.Api.get_self_info()         # {user_id, user_name, host}

# Версия
result = await mc.Api.get_version()

# Множественные серверы
result = await mc.Api.Using("server2").get_player_list()

Поддерживаемые стандартные действия

Расширенные действия платформы

Через Api.exec(cmd) можно выполнить любую команду RCON (эквивалентно call_api("exec", command=...)):

# Управление белым списком
await mc.Api.exec("whitelist add Alex")
await mc.Api.exec("whitelist remove Alex")

# Управление сервером
await mc.Api.exec("time set day")
await mc.Api.exec("weather clear")
await mc.Api.exec("op Alex")
await mc.Api.exec("kick Steve")

# Данные и счётчики
await mc.Api.exec("scoreboard objectives add kills deathCount")

Внимание по безопасности: Api.exec предоставляет полный контроль над консолью сервера (включая stop/deop и т.д.), не передавайте незащищённый интерфейс вызовам из ненадёжных источников.

Неподдерживаемые стандартные действия

Следующие стандартные действия не поддерживаются RCON, вызов возвращает retcode=10002 или 33001 (неподключено):

• delete_message (в Minecraft нет возможности удаления сообщений)
• get_friend_list / get_group_list (используйте get_player_list как замену)

Общий входной интерфейс действий

# send_message: эквивалент Send-цепочки
result = await mc.call_api(
    "send_message",
    _account_id="default",
    target_type="user", target_id="Steve",
    message=[{"type": "text", "data": {"text": "hi"}}],
)

Формат возвращаемых значений методов отправки

{
    "status": "ok",                  # ok / failed
    "retcode": 0,                    # 0 — успех; 33001 — не подключено/ошибка выполнения; 10002 — не поддерживается
    "data": {"command_output": "..."},  # Ответ RCON-команды
    "self": {"platform": "minecraft", "user_id": "mc1"},
    "message_id": "uuid",            # Созданный идентификатор сообщения (tellraw/say не имеют реального message_id)
    "message": "",
    "minecraft_raw": {"output": "..."}
}

Типы событий (при enable_log_tail = true)

Необходимо проверять platform == "minecraft", чтобы использовать функции данной платформы. RCON-протокол не может получать события чата (чистый протокол запрос-ответ), события зависят от прослушивания логов.

Сопоставление событий

Примеры полей событий

# Сообщение
{
  "id": "uuid",
  "time": 1793277000,
  "type": "message",
  "detail_type": "server",
  "platform": "minecraft",
  "self": {"platform": "minecraft", "user_id": "mc1", "user_name": "mc1", "account_id": "default"},
  "user_id": "Steve",                      # Имя игрока
  "message": [{"type": "text", "data": {"text": "Привет, мир"}}],
  "alt_message": "Привет, мир",
  "group_id": "mc1",                       # bot_id
  "minecraft_raw": {"line": "[12:34:56] [Server thread/INFO]: <Steve> Привет, мир"},
  "minecraft_raw_type": "log_line"
}

# Присоединение (notice)
{
  "type": "notice",
  "detail_type": "server_joined",          # или server_left
  "user_id": "Alex",
  "operator_id": "Alex",
  "group_id": "mc1",
  "minecraft_raw": {"line": "..."},
  "minecraft_raw_type": "log_line"
}

Удаление дубликатов

Ответы команд say / tellraw также записываются в лог. Адаптер при отправке сохраняет отпечаток содержимого (окно в 30 секунд), при появлении в логе одинакового содержимого событие пропускается, чтобы избежать повторной отправки сообщений бота.

Примечания

1. RCON не может получать события чата: ограничение протокола (чистый запрос-ответ), события должны быть включены через прослушивание логов
2. Доступность пути к логам: адаптер и сервер должны работать на одной машине или каталог логов должен быть смонтирован (в контейнерных сценариях смонтируйте logs/)
3. Формат логов: зависит от vanilla / основных серверов (Paper, Fabric и т.д.); модифицированные плагины (например, пользовательские плагины чата) могут нарушить формат
4. Ограничение параллелизма RCON: Minecraft RCON обрабатывает команды последовательно по одному соединению; адаптер содержит внутреннюю блокировку и поддерживает активную связь (пустая команда каждые 30 секунд)
5. Окно удаления дубликатов: одинаковое содержимое в течение 30 секунд отправляется только один раз
6. Безопасность: Api.exec предоставляет права консоли, не передавайте его ненадёжным вызывающим сторонам