Library for communicating with and controlling Minecraft servers via MCPQ plugin
Project description
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.
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!
Usage
After getting a server and compatible plugin setup and running, the only thing left to do is to install the python library:
pip3 install mcpq
Get 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)
Documentation
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.
Versions
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.
Build Instructions
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.
License
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.