Введение в 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].

Установка плагина

  1. Скачайте сервер Paper (рекомендуется) для нужной версии Minecraft
  2. Скачайте mcpq-<version>.jar со страницы релизов
  3. Поместите JAR-файл в папку plugins сервера
  4. Запустите сервер. Плагин создаст конфигурационный файл 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.text
getBlock(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].