Введение в MCPQ
MCPQ (Minecraft Protobuf Queries) — это современная экосистема для управления Minecraft Java Edition из Python и других языков программирования. В отличие от устаревших решений, MCPQ использует gRPC и Protocol Buffers для быстрой и надежной связи.
Вдохновение: Библиотека вдохновлена MCPI и плагином RaspberryJuice, но предлагает современный подход для актуальных версий Minecraft [citation:1][citation:2].
Быстрый старт:
Базовый пример
from mcpq import Minecraft, Vec3 # Подключение к серверу (по умолчанию localhost:1789) mc = Minecraft() # Отправить сообщение в чат mc.postToChat("Привет из Python!") # Работа с блоками pos = Vec3(0, 64, 0) block = mc.getBlock(pos) # Получить блок mc.setBlock("diamond_block", pos) # Установить алмазный блок # Получить позицию игрока player_pos = mc.player.getTilePos() print(f"Игрок на позиции: {player_pos}")
Требования: Библиотека требует Python 3.10 или выше из-за использования современных аннотаций типов [citation:1][citation:3].
Установка библиотеки
Установка из PyPI
Установка через pip
# Базовая установка pip install mcpq # Установка с дополнительными инструментами (например, черепашка) pip install mcpq[tools] # Установка из GitHub pip install git+https://github.com/mcpq/mcpq-python.git@v2.0.1
Для Raspberry Pi
pip3 install mcpq # Доступно в piwheels [citation:4] Текущая версия: 2.0.1 (май 2025) [citation:3]
Настройка сервера Minecraft
Плагин mcpq-plugin
Для работы библиотеки необходим сервер Paper или Spigot с установленным плагином mcpq-plugin [citation:2].
Установка плагина
- Скачайте сервер Paper (рекомендуется) для нужной версии Minecraft
- Скачайте
mcpq-<version>.jarсо страницы релизов - Поместите JAR-файл в папку
pluginsсервера - Запустите сервер. Плагин создаст конфигурационный файл
plugins/mcpq/config.yml
Таблица совместимости версий
| Major (Протокол) | Minor (Плагин) | Paper | Spigot | Minecraft версии | Файл |
|---|---|---|---|---|---|
| 1 | 0 | ✅ | ✅ | 1.18.2 - 1.21.4 | mcpq-1.0.jar |
| 2 | 0 | ✅* | ✅* | 1.20.1+ | mcpq-2.0.jar |
| 2 | 1 | ✅ | ❌ | 1.20.1+ | mcpq-2.1.jar |
* Ограниченный вывод для блокирующих команд [citation:2]
Важно про Paper и Spigot: Начиная с Minecraft 1.21.4, Paper больше не является форком Spigot. Плагины, собранные против Paper API, не совместимы с Spigot. Для Spigot существует отдельная ветка
main-spigot [citation:2].
Конфигурация плагина
config.yml
# Хост для подключения (localhost только локально, 0.0.0.0 для всех) host: localhost # Порт для gRPC соединений port: 1789 # Режим отладки для gRPC debug: false
Безопасность: По умолчанию плагин принимает соединения только с
localhost. Для удаленного подключения измените host на 0.0.0.0, но помните, что соединение не шифруется! [citation:2][citation:6]
Подключение к серверу
Minecraft(host='localhost', port=1789)
Создает подключение к серверу с плагином MCPQ
host str
port int
Соединение thread-safe и переиспользуемое [citation:6]
.host / .port
Свойства для получения адреса и порта подключения
.Block / .EntityType / .NBT / .Vec3
Алиасы для конструкторов соответствующих классов
Различные способы подключения
from mcpq import Minecraft # Подключение к локальному серверу (по умолчанию) mc = Minecraft() print(f"Подключено к {mc.host}:{mc.port}") # Подключение к удаленному серверу mc_remote = Minecraft(host="192.168.1.100", port=1789) # Использование алиасов для удобства pos = mc.Vec3(10, 20, 30) # вместо Vec3(10, 20, 30) block_type = mc.Block("diamond_block") entity = mc.EntityType("creeper") nbt_data = mc.NBT({"unbreakable": {}})
Основные методы API
postToChat(*objects, sep=' ')
Отправляет сообщение в игровой чат
objects any
sep str
Поддерживает цветной текст через
mcpq.textgetBlock(pos) / setBlock(block, pos)
Получить или установить блок по координатам
pos Vec3
block str | int | Block
Можно использовать строковые ID ("diamond_block")
getHighestPos(x, z)
Получает самую высокую точку поверхности
Возвращает: Vec3 с координатами
getPlayer(name=None)
Получает онлайн игрока по имени или любого
Возвращает: Player объект
getPlayerList(names=None)
Получает список всех онлайн игроков
Возвращает: list[Player]
getOfflinePlayer(name)
Получает игрока по имени даже если он офлайн
spawnEntity(entity_type, pos)
Создает сущность в указанной позиции
entity_type str | EntityType
Возвращает: Entity объект
getEntityById(entity_id)
Получает сущность по уникальному ID
runCommand(command)
Выполняет команду как /command (не ждет результата)
runCommandBlocking(command)
Выполняет команду и возвращает ответ сервера
getMinecraftVersion()
Возвращает версию Minecraft сервера
getPluginVersion()
Возвращает версию MCPQ плагина
.overworld / .nether / .end
Свойства для доступа к основным мирам
getWorldByKey(key)
Получает мир по внутреннему ключу ("minecraft:overworld")
getWorldByName(name)
Получает мир по имени папки ("world")
Расширенный пример
from mcpq import Minecraft, text mc = Minecraft() # Цветной чат mc.postToChat(text.RED + text.BOLD + "ВНИМАНИЕ!" + text.RESET + " Сервер управляется Python") # Получить игроков онлайн players = mc.getPlayerList() for player in players: mc.postToChat(f"Привет, {player.name}!") # Работа с блоками с данными pos = mc.getHighestPos(10, 10).up(1) # Получить случайный блок, название которого заканчивается на "_stairs" stairs = mc.blocks.endswith("_stairs").choice() # Установить ступеньки с waterlogged=true mc.setBlock(stairs.withData({"waterlogged": True}), pos) # Спавн крипера с эффектом creeper = mc.spawnEntity("creeper", pos.up(1)) creeper.giveEffect("invisibility") # Бесконечная невидимость # Телепорт крипера к игроку creeper.pos = mc.getPlayer().pos
Модуль Turtle (Черепашка)
Требует mcpq[tools]
Модуль mcpq.tools.Turtle предоставляет интерфейс, вдохновленный Logo Turtle, для простого рисования и строительства [citation:1][citation:3].
Turtle(mc)
Создает черепашку в позиции текущего игрока
fd(distance) / forward(distance)
Двигается вперед на указанное расстояние (блоки)
bk(distance) / back(distance)
Двигается назад
right(angle) / left(angle)
Поворачивает направо/налево на угол (градусы)
up() / down()
Поворачивает вверх/вниз
speed(value)
Устанавливает скорость движения (блоков в секунду)
block(block_type)
Устанавливает тип блока, который черепашка оставляет
Рисование квадрата черепашкой
from mcpq import Minecraft from mcpq.tools import Turtle mc = Minecraft() t = Turtle(mc) # Создать черепашку у игрока t.speed(10) # Скорость 10 блоков/сек t.block("gold_block") # Оставлять золотые блоки # Нарисовать квадрат 10x10 for i in range(4): t.fd(10).right(90)
Рисование звезды
import math # Нарисовать пятиконечную звезду t = Turtle(mc) t.speed(15) t.block("glowstone") for i in range(5): t.fd(15) t.right(144) # Угол для звезды
Обработка событий
.events.block_hit
Событие при ударе по блоку
.events.chat_post
Событие при отправке сообщения в чат
.events.player_join
Событие при входе игрока
.events.player_quit
Событие при выходе игрока
Мониторинг событий
from mcpq import Minecraft import time mc = Minecraft() # Регистрация обработчиков событий mc.events.block_hit.register(lambda e: mc.postToChat(f"Блок {e.pos} был ударен!")) mc.events.chat_post.register(lambda e: print(f"Чат: {e.message}")) mc.events.player_join.register(lambda e: mc.postToChat(f"Добро пожаловать, {e.player.name}!")) print("Слушаю события... Ctrl+C для выхода") try: while True: time.sleep(1) except KeyboardInterrupt: print("Монитор остановлен")
Совет: Можно зарегистрировать
mc.postToChat напрямую как обработчик, чтобы выводить события в чат для отладки [citation:6].
Практические примеры
Построить маяк
def build_beacon(mc, center): # Пирамида из изумрудов for y in range(4): size = 3 - y mc.setBlocks( center.x - size, center.y + y, center.z - size, center.x + size, center.y + y, center.z + size, "emerald_block" ) # Маяк на вершине mc.setBlock("beacon", center.up(4)) # Стеклянная оболочка mc.setBlocks( center.x - 2, center.y + 4, center.z - 2, center.x + 2, center.y + 6, center.z + 2, "glass" ) # Очистить внутри mc.setBlocks( center.x - 1, center.y + 4, center.z - 1, center.x + 1, center.y + 5, center.z + 1, "air" )
Автоматический телепорт
def teleport_on_hit(mc): # Телепортировать игрока на 10 блоков вверх при ударе по блоку def on_hit(event): player = mc.getPlayer(event.player) player.pos = player.pos.up(10) mc.postToChat(f"{player.name} улетел!") mc.events.block_hit.register(on_hit) mc.postToChat("Режим телепортации активирован! Бей по блокам!")
Генератор гор
import random def generate_mountain(mc, base_x, base_z, height): for y in range(height): radius = height - y for dx in range(-radius, radius + 1): for dz in range(-radius, radius + 1): if dx*dx + dz*dz <= radius*radius: block = "stone" if y > height - 3: block = "grass_block" if random.random() > 0.3 else "snow_block" mc.setBlock(block, mc.Vec3(base_x + dx, y, base_z + dz))
Приветствие новых игроков
from mcpq import text def welcome_system(mc): def on_join(event): msg = (text.GREEN + text.BOLD + f"Добро пожаловать, {event.player.name}!" + text.RESET + " На сервере " + text.GOLD + str(len(mc.getPlayerList())) + text.RESET + " игроков") mc.postToChat(msg) # Дать стартовый набор mc.runCommand(f"give {event.player.name} diamond_pickaxe 1") mc.runCommand(f"give {event.player.name} cooked_beef 16") mc.events.player_join.register(on_join) mc.postToChat("Система приветствий активирована")
Часто задаваемые вопросы
Какие версии Minecraft поддерживаются?
MCPQ поддерживает современные версии Minecraft от 1.18.2 до 1.21.4+ в зависимости от версии плагина [citation:2]. Подробнее в таблице совместимости выше.
Как выбрать правильную версию библиотеки?
Версия библиотеки имеет формат
major.minor.patch. Первые две цифры (major.minor) должны совпадать с версией плагина на сервере. Например, для плагина 2.0 нужна библиотека 2.0.x [citation:1][citation:3]. Насколько безопасно соединение?
Соединение не шифруется. Рекомендуется подключаться только с localhost или использовать VPN/SSH-туннель для удаленного доступа [citation:2][citation:6].
Почему требуется Python 3.10+?
Библиотека использует современные аннотации типов, которые стали доступны начиная с Python 3.10. Более старые версии не поддерживаются [citation:1].
Модуль Turtle требует дополнительной установки?
Да, установите с опцией
pip install mcpq[tools], чтобы получить все зависимости для модуля mcpq.tools [citation:3]. Совместим ли клиент новой версии со старым плагином?
Нет. Клиент старой версии может работать с новым плагином (обратная совместимость protobuf), но новый клиент со старым плагином — не поддерживается [citation:2].
Чем MCPQ отличается от RaspberryJuice?
MCPQ использует современные технологии gRPC и Protocol Buffers, поддерживает актуальные версии Minecraft, имеет асинхронную архитектуру и более богатый API для работы с сущностями, NBT и событиями [citation:1][citation:2].