📌Overview

Purpose: The MCPQ Python Client Library is designed to facilitate interaction with a Minecraft Java Server (e.g., Spigot or Paper) using Python, enabling modern communication through the MCPQ plugin.

Overview: This library provides a modernized approach to control Minecraft servers via Python, inspired by earlier versions like MCPI. It utilizes Protocol Buffers and gRPC for efficient communication with servers, ensuring compatibility with newer Minecraft versions.

Key Features:

Modern Communication: Utilizes Protocol Buffers and gRPC for streamlined interactions between the Python client and Minecraft server, enhancing performance and compatibility.
Pythonic Interface: Offers an intuitive interface for Python developers, including convenient functions for sending commands and manipulating the game world (e.g., setting blocks, posting messages).
Turtle Module Integration: Comes with an integrated Turtle module for easy navigation and automation within the Minecraft environment, helping users learn coding while having fun.

Minecraft Protobuf Queries (MCPQ) Python Client Library

This library is designed to control a Minecraft Java Server, such as Spigot or Paper running the mcpq plugin, with Python.

It is inspired by MCPI and its plugin RaspberryJuice, aiming for a modern approach to communication between server and client that works with recent Minecraft versions.

The library uses Protocol Buffers and the gRPC library and protocols to communicate with the plugin on the server.

Requires Python 3.10+ due to the use of new type annotations.

Usage

After setting up a server and compatible plugin, install the Python library:

pip3 install mcpq

Example code:

from mcpq import Minecraft, Vec3

mc = Minecraft()  # connect to server on localhost

mc.postToChat("Hello Minecraft!")
pos = Vec3(0, 0, 0)  # origin of world, coordinates x, y, and z = 0
block = mc.getBlock(pos)  # get block at origin
mc.setBlock("obsidian", pos)  # replace block with obsidian
mc.postToChat("Replaced", block, "with obsidian at", pos)

A useful starting point is the turtle module:

from mcpq import Minecraft, Vec3
from mcpq.tools import Turtle

mc = Minecraft()  # connect to server on localhost
t = Turtle(mc)  # spawn turtle at player position
t.speed(10)

for i in range(4):
    t.fd(10).right(90)

Documentation

The full documentation is available online and hosts the latest released version.

Older documentation versions can be accessed by checking out the desired release with git and serving the docs locally.

Versions

Check the Minecraft and plugin version compatibility in the plugin's version table.

Version numbering is major.minor.patch:

major: protocol version/tag
minor: plugin version/tag
patch: patches and additional library functionality independent of protocol or plugin

The first two numbers (major.minor) correspond to the plugin version the library targets.

The library should work with newer plugin versions unless breaking changes occur; however, it is unlikely to work with older plugin versions, especially across major versions.

Ensure the first two numbers (major.minor) of the library version match the plugin's.

Build Instructions

The library is published on PyPI and can be installed with:

pip3 install mcpq

Alternatively, install directly from GitHub:

pip install git+https://github.com/mcpq/mcpq-python.git@<tag/branch>

If cloned locally, install with:

pip install .

To build locally:

python -m build

This creates wheel and dist packages in dist/. Install the resulting tar package with pip.

For protobuf file rebuilds after switching protocol versions, clone the proto submodule, checkout the appropriate tag, and run:

make proto

License

This project is licensed under LGPLv3.

The intent is to allow the software to be used in any project, including commercial or closed-source.

Modifications to the licensed software must be shared under the same license.