This library is designed to control a Minecraft Java Server, such as Spigot or Paper running the mcpq plugin, with Python.
This library is heavily inspired by MCPI (and its corresponding plugin RaspberryJuice) and attempts a more modern approach for communication between server and client that also works for more modern versions of Minecraft.
This library uses Protocol Buffers and the gRPC library and protocols to communicate with the plugin on the server.
Due to the use of the new type annotations Python 3.10+ is required!
After getting a server and compatible plugin setup and running, the only thing left to do is to install the python library:
pip3 install mcpqGet coding!
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 good place to start 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)You can explore the full documentation for the library by visiting the docs, which hosts the latest released version.
Only the most recent version of the documentation is published there.
If you need to view older versions, you can use git checkout vX.Y.Z to switch to a desired release, then run make show_docs to serve the docs folder locally at localhost:8000.
For documentation related to non-tagged commits, run make live_docs to build the docs first, as the docs folder is only committed for tagged releases.
First off, to see which version of the plugin is compatible with which Minecraft version, checkout this Minecraft version table.
The three tuple major.minor.patch of the version refers to the following:
- major: protocol version/tag
- minor: plugin version/tag
- patch: is incremented with patches and additional functionality of this library independend of protocol or plugin
In other words, the first two numbers (major.minor) refer to the plugin version the library was written against.
E.g. the Python library version 1.0.X would require plugin version 1.0 or newer
This Python library should work for any newer versions of the plugin if everything works out and no breaking changes are introduced, at least across minor versions (see table). On the other hand, the library will most likely not work for older versions of the plugin, especially not across major versions.
TLDR; make sure the first 2 numbers (major.minor) of the library version are the same as the plugin's and choose the last number as high as possible.
The library is currently published on PyPI. The package can be downloaded from there with pip3 install mcpq.
You can also install this package directly by using pip install git+https://github.com/mcpq/mcpq-python.git@<tag/branch> to install it directly from Github (git is required for this).
If you cloned the repository already then pip install . can be used.
Building the library locally can be done by using python -m build, which will build the wheel and dist packages in dist/*.
Afterwards the tar file can be installed with pip: pip install mcpq-0.0.0.tar.gz.
If you want to play around with the library itself you can also clone the repository as git submodule.
If you want to rebuild the protobuf files, for example, because you switched to a new major version of the protocol, first clone the proto submodule with git submodule update --init --recursive, then cd into the directory and git checkout <tag> the version you want to use.
Afterwards you can use make proto to re-build the stubs.
Note: The intent behind the chosen license is to allow the licensed software to be used (without modification) in any type of project, even commercial or closed-source ones. However, if you make changes or modifications to the licensed software itself, those modifications must be shared under the same license. Checkout this blog for an in-depth explanation.