Введение в MCPI

MCPI (Minecraft Pi API) - официальная Python библиотека для программирования Minecraft Pi Edition. Она позволяет взаимодействовать с игрой через Python скрипты.

История: Библиотека была создана Mojang специально для образовательной версии Minecraft на Raspberry Pi.
Быстрый старт:
Базовый пример
from mcpi import minecraft
from mcpi import block

# Создание подключения
mc = minecraft.Minecraft.create()

# Получение позиции игрока
pos = mc.player.getTilePos()
print(f"Позиция игрока: {pos.x}, {pos.y}, {pos.z}")

# Установка блока
mc.setBlock(pos.x + 1, pos.y, pos.z, block.STONE.id)

Установка библиотеки

Для Linux/Raspberry Pi

Установка через pip
# Установка библиотеки
pip install mcpi

# Или для Python 3
pip3 install mcpi

# Обновление до последней версии
pip install --upgrade mcpi

Для Windows

Ручная установка
# 1. Скачайте библиотеку с GitHub # 2. Распакуйте архив # 3. Установите:
cd mcpi-master
python setup.py install

# Или напрямую через pip с GitHub
pip install git+https://github.com/martinohanlon/mcpi.git
Примечание: На Raspberry Pi библиотека обычно предустановлена вместе с Minecraft Pi Edition.

Подключение к Minecraft

Основной метод
Minecraft.create()
Создает подключение к локальному экземпляру Minecraft
Возвращает: объект Minecraft
Minecraft.create("адрес", порт)
Подключение к удаленному серверу Minecraft Pi
адрес str
порт int
По умолчанию: 127.0.0.1:4711
Примеры подключения
from mcpi import minecraft

# Подключение к локальному Minecraft
mc = minecraft.Minecraft.create()
print("Подключено к локальному Minecraft")

# Подключение к удаленному серверу try:
    mc_remote = minecraft.Minecraft.create("192.168.1.100", 4711)
    print("Подключено к удаленному серверу")
except ConnectionError as e:
    print(f"Ошибка подключения: {e}")

# Проверка соединения try:
    pos = mc.player.getPos()
    print(f"Соединение активно. Позиция: {pos}")
except:
    print("Нет соединения с Minecraft")
Важно: Перед запуском скрипта убедитесь, что Minecraft Pi Edition запущен и находится в игровом мире.

Основные методы API

Ключевые методы для взаимодействия с миром Minecraft.

getBlock(x, y, z)
Получает ID блока по координатам
x, y, z int
Возвращает: int (ID блока)
setBlock(x, y, z, blockId, blockData=0)
Устанавливает блок по координатам
blockId int
blockData int (опционально)
Возвращает: None
setBlocks(x1, y1, z1, x2, y2, z2, blockId, blockData=0)
Заполняет область блоками
Возвращает: None
getHeight(x, z)
Получает высоту поверхности в точке
Возвращает: int (координата Y)
getPlayerEntityIds()
Получает список ID всех игроков
Возвращает: list[int]
getPlayerEntityId(name)
Получает ID игрока по имени
name str
Возвращает: int (ID игрока)
saveCheckpoint()
Сохраняет текущую позицию игрока как точку возрождения
Возвращает: None
restoreCheckpoint()
Возвращает игрока в сохраненную точку
Возвращает: None

Методы для работы с игроком

Игрок
player.getPos()
Получает точные координаты игрока (float)
Возвращает: Vec3(x, y, z)
player.getTilePos()
Получает координаты блока под игроком (int)
Возвращает: Vec3(x, y, z)
player.setPos(x, y, z)
Телепортирует игрока в точку
Возвращает: None
player.setTilePos(x, y, z)
Телепортирует игрока к блоку
Возвращает: None
player.getDirection()
Получает вектор направления взгляда
Возвращает: Vec3
player.getRotation()
Получает угол поворота игрока
Возвращает: float
player.getPitch()
Получает угол наклона головы вверх/вниз
Возвращает: float
Пример работы с игроком
from mcpi import minecraft
import time

mc = minecraft.Minecraft.create()

# Получить позицию игрока
pos = mc.player.getPos()
tile_pos = mc.player.getTilePos()
print(f"Точная позиция: {pos.x:.2f}, {pos.y:.2f}, {pos.z:.2f}")
print(f"Позиция блока: {tile_pos.x}, {tile_pos.y}, {tile_pos.z}")

# Получить направление взгляда
direction = mc.player.getDirection()
rotation = mc.player.getRotation()
pitch = mc.player.getPitch()
print(f"Направление: {direction}")
print(f"Поворот: {rotation}°, Наклон: {pitch}°")

# Телепортировать игрока вверх
mc.player.setPos(pos.x, pos.y + 10, pos.z)
print("Игрок телепортирован на 10 блоков вверх")

# Сохранить точку возрождения
mc.saveCheckpoint()

Чат и сообщения

Чат
postToChat(message)
Отправляет сообщение в чат
message str
Возвращает: None
events.pollChatPosts()
Получает последние сообщения из чата
Возвращает: list[ChatPost]
events.pollBlockHits()
Получает события ударов по блокам
Возвращает: list[BlockEvent]
events.clearAll()
Очищает все события
Возвращает: None
Пример: Чат-бот
from mcpi import minecraft
import time

mc = minecraft.Minecraft.create()

# Отправить приветствие
mc.postToChat("Привет, я Python-бот!")
time.sleep(2)

# Отправить информацию о позиции
pos = mc.player.getTilePos()
mc.postToChat(f"Ты находишься на X:{pos.x} Y:{pos.y} Z:{pos.z}")
time.sleep(2)

# Мониторинг чата print("Слушаю чат... (Ctrl+C для выхода)")
try:
    while True:
        chat_events = mc.events.pollChatPosts()
        for event in chat_events:
            message = event.message
            entityId = event.entityId
            print(f"Игрок {entityId} написал: {message}")
            
            # Ответить на приветствие if "привет" in message.lower():
                mc.postToChat("Привет тебе, игрок!")
        
        time.sleep(0.1)
except KeyboardInterrupt:
    print("Бот остановлен")

Блоки и их ID

Модуль block: Содержит константы для всех блоков Minecraft. Используйте block.НАЗВАНИЕ.id для получения ID.
Импорт модуля block
from mcpi import block

# Основные блоки print(f"ID воздуха: {block.AIR.id}")           # 0 print(f"ID камня: {block.STONE.id}")          # 1 print(f"ID травы: {block.GRASS.id}")          # 2 print(f"ID земли: {block.DIRT.id}")           # 3 print(f"ID булыжника: {block.COBBLESTONE.id}") # 4 # Дерево print(f"ID досок: {block.WOOD_PLANKS.id}")     # 5 print(f"ID саженца: {block.SAPLING.id}")       # 6 print(f"ID древесины: {block.WOOD.id}")        # 17 print(f"ID листьев: {block.LEAVES.id}")        # 18 # Полезные ископаемые print(f"ID угля: {block.COAL_ORE.id}")         # 16 print(f"ID железа: {block.IRON_ORE.id}")        # 15 print(f"ID золота: {block.GOLD_ORE.id}")        # 14 print(f"ID алмаза: {block.DIAMOND_ORE.id}")     # 56 # Инструменты и механизмы print(f"ID верстака: {block.CRAFTING_TABLE.id}") # 58 print(f"ID печи: {block.FURNACE_ACTIVE.id}")     # 62 print(f"ID сундука: {block.CHEST.id}")          # 54

Популярные блоки и их ID

ID Название блока Константа Описание
0 Воздух block.AIR Пустой блок
1 Камень block.STONE Основной блок мира
2 Трава block.GRASS Поверхностный блок
3 Земля block.DIRT Под травой
8 Вода block.WATER Стационарная вода
10 Лава block.LAVA Стационарная лава
12 Песок block.SAND Падающий блок
17 Древесина block.WOOD Бревна деревьев
20 Стекло block.GLASS Прозрачный блок
35 Шерсть block.WOOL 16 цветов (данные 0-15)
41 Золотой блок block.GOLD_BLOCK Декоративный блок
57 Алмазный блок block.DIAMOND_BLOCK Самый прочный блок

Практические примеры

Построить дом

def build_house(mc, x, y, z, size=5):
    # Стены из дерева
    mc.setBlocks(x, y, z, 
                 x+size, y+size, z+size, 
                 block.WOOD_PLANKS.id)
    
    # Внутреннее пространство
    mc.setBlocks(x+1, y+1, z+1,
                 x+size-1, y+size-1, z+size-1,
                 block.AIR.id)
    
    # Дверь
    mc.setBlock(x+size//2, y+1, z, block.AIR.id)
    mc.setBlock(x+size//2, y+2, z, block.AIR.id)
    
    # Окна
    mc.setBlock(x, y+2, z+size//2, block.GLASS.id)
    mc.setBlock(x+size, y+2, z+size//2, block.GLASS.id)
    
    return (x+size//2, y, z+size//2)

Случайные башни

import random

def random_towers(mc, center_x, center_z, radius, count):
    for _ in range(count):
        # Случайная позиция в радиусе
        angle = random.random() * 3.14159 * 2
        distance = random.random() * radius
        x = center_x + int(distance * math.cos(angle))
        z = center_z + int(distance * math.sin(angle))
        
        # Высота земли
        y = mc.getHeight(x, z)
        
        # Случайная высота башни
        height = random.randint(5, 15)
        
        # Случайный материал
        materials = [block.STONE.id, 
                    block.BRICK_BLOCK.id,
                    block.OBSIDIAN.id,
                    block.GLOWSTONE_BLOCK.id]
        material = random.choice(materials)
        
        # Построить башню
        mc.setBlocks(x, y, z, 
                     x, y+height, z, 
                     material)

ТНТ пушка

def tnt_cannon(mc, x, y, z):
    # Основание пушки
    mc.setBlocks(x-1, y, z-1,
                 x+1, y, z+1,
                 block.OBSIDIAN.id)
    
    # Ствол пушки
    mc.setBlocks(x, y+1, z,
                 x, y+3, z,
                 block.IRON_BLOCK.id)
    
    # Заряд ТНТ
    mc.setBlock(x, y+4, z, block.TNT.id, 1)
    
    # Активатор (рычаг)
    mc.setBlock(x+1, y+1, z, block.LEVER.id, 1)
    
    mc.postToChat("ТНТ пушка построена! Активируй рычаг!")

Платформер

def create_parkour(mc, start_x, start_y, start_z):
    # Стартовая платформа
    mc.setBlocks(start_x-2, start_y-1, start_z-2,
                 start_x+2, start_y-1, start_z+2,
                 block.GOLD_BLOCK.id)
    
    # Серия платформ
    platforms = [
        (start_x+5, start_y+2, start_z, block.STONE.id),
        (start_x+10, start_y+4, start_z, block.IRON_BLOCK.id),
        (start_x+15, start_y+1, start_z, block.EMERALD_BLOCK.id),
        (start_x+20, start_y+6, start_z, block.DIAMOND_BLOCK.id)
    ]
    
    for px, py, pz, material in platforms:
        mc.setBlocks(px-1, py-1, pz-1,
                     px+1, py-1, pz+1,
                     material)
    
    # Финишная платформа
    mc.setBlocks(start_x+25, start_y, start_z-3,
                 start_x+30, start_y, start_z+3,
                 block.GLOWSTONE_BLOCK.id)
    
    mc.postToChat("Паркур создан! Доберись до светящегося камня!")

Работа с событиями

Мониторинг событий в реальном времени
from mcpi import minecraft
import time

mc = minecraft.Minecraft.create()

print("Запущен монитор событий Minecraft...")
print("Нажимайте на блоки и пишите в чат!")
print("Ctrl+C для выхода\n")

try:
    while True:
        # Проверка сообщений в чате
        chat_posts = mc.events.pollChatPosts()
        for post in chat_posts:
            print(f"[ЧАТ] Игрок {post.entityId}: {post.message}")
            
        # Проверка ударов по блокам
        block_hits = mc.events.pollBlockHits()
        for hit in block_hits:
            pos = hit.pos
            face = hit.face
            print(f"[УДАР] Блок на {pos.x}, {pos.y}, {pos.z} (сторона: {face})")
            
            # Изменить блок при ударе
            block_id = mc.getBlock(pos.x, pos.y, pos.z)
            if block_id != block.TNT.id:
                mc.setBlock(pos.x, pos.y, pos.z, block.GLOWING_OBSIDIAN.id)
                mc.postToChat("Блок подсвечен!")
        
        time.sleep(0.1)

except KeyboardInterrupt:
    print("\nМонитор событий остановлен")
Идея проекта: Создайте систему безопасности для дома, которая активируется при нажатии на блок-кнопку и отправляет сообщение в чат о вторжении.

Часто задаваемые вопросы

MCPI работает с обычным Minecraft?
Нет, MCPI работает только с Minecraft Pi Edition (специальная версия для Raspberry Pi) и не совместим с Java или Bedrock Edition.
Нужен ли Raspberry Pi?
Да, для работы с MCPI необходим Raspberry Pi с установленной Minecraft Pi Edition. На других платформах библиотека не будет работать.
Какие функции недоступны в MCPI?
MCPI имеет ограниченный функционал: нет работы с инвентарем, крафтом, мобами, погодой, временем суток и сложными блоками (редстоун, порталы и т.д.).
Ошибка "Connection refused"
1. Убедитесь, что Minecraft Pi Edition запущен. 2. Проверьте, что игра находится в мире (не в меню). 3. Для удаленного подключения убедитесь, что сервер разрешает внешние подключения.
Как ускорить построение больших структур?
Используйте setBlocks() вместо множественных вызовов setBlock(). Для очень больших структур разбивайте построение на части с помощью time.sleep().
Подходит ли MCPI для обучения?
Да, MCPI отлично подходит для обучения программированию детей и начинающих благодаря простому API и визуальному результату работы кода.