Beet documentation#
Welcome! This is the place where you'll eventually find everything there is to know about the beet
project. The documentation is currently a work-in-progress. You're welcome to help write guides and contribute example use-cases. In the meantime, don't be afraid to check out the code!
You can follow the development of the project, discuss ideas, get help, and hang out with cool people interested in map-making and programming on our brand new discord! You can also ask questions about beet
and get general help about Minecraft map-making on the Minecraft Commands discord server.
Beet - The Minecraft pack development kit
Minecraft Commands - General discussions about commands and map-making
Introduction#
Minecraft resource packs and data packs work well as distribution formats but can be pretty limiting as authoring formats. You can quickly end up having to manage hundreds of files, some of which might be buried within the bundled output of various generators.
The beet
project is a development kit that tries to unify data pack and resource pack tooling into a single pipeline. The community is always coming up with pre-processors, frameworks, and generators of all kinds to make the developer experience more ergonomic. With beet
you can seamlessly integrate all these tools in your project.
Screencasts#
Quick start https://youtu.be/JGrJTOhG3pY
Command-line https://youtu.be/fQ9up0ELPNE
Library overview https://youtu.be/LDvV4_l-PSc
Plugins basics https://youtu.be/XTzKmvHqd1g
Pipeline configuration https://youtu.be/QsnQncGxAAs
Library#
from beet import ResourcePack, Texture
# Open a zipped resource pack and add a custom stone texture
with ResourcePack(path="stone.zip") as assets:
assets["minecraft:block/stone"] = Texture(source_path="custom.png")
The beet
library provides carefully crafted primitives for working with Minecraft resource packs and data packs.
Create, read, edit and merge resource packs and data packs
Handle zipped and unzipped packs
Fast and lazy by default, files are transparently loaded when needed
Statically typed API enabling rich intellisense and autocompletion
First-class
pytest
integration with detailed assertion explanations
Toolchain#
from beet import Context, Function
def greet(ctx: Context):
"""Plugin that adds a function for greeting the player."""
ctx.data["greet:hello"] = Function(["say hello"], tags=["minecraft:load"])
The beet
toolchain is designed to support a wide range of use-cases. The most basic pipeline will let you create configurable resource packs and data packs, but plugins make it easy to implement arbitrarily advanced workflows and tools like linters, asset generators and function pre-processors.
Compose plugins that can inspect and edit the generated resource pack and data pack
Configure powerful build systems for development and creating releases
First-class template integration approachable without prior Python knowledge
Link the generated resource pack and data pack to Minecraft
Automatically rebuild the project on file changes with watch mode
Batteries-included package that comes with a few handy plugins out of the box
Rich ecosystem, extensible CLI, and powerful generator and worker API
Installation#
The package can be installed with pip
.
$ pip install beet
To create and edit images programmatically you should install beet
with the image
extra or install Pillow
separately.
$ pip install beet[image]
$ pip install beet Pillow
You can make sure that beet
was successfully installed by trying to use the toolchain from the command-line.
$ beet --help
Usage: beet [OPTIONS] COMMAND [ARGS]...
The beet toolchain.
Options:
-p, --project PATH Select project.
-s, --set OPTION Set config option.
-l, --log LEVEL Configure output verbosity.
-v, --version Show the version and exit.
-h, --help Show this message and exit.
Commands:
build Build the current project.
cache Inspect or clear the cache.
link Link the generated resource pack and data pack to Minecraft.
watch Watch the project directory and build on file changes.
Contributing#
Contributions are welcome. Make sure to first open an issue discussing the problem or the new feature before creating a pull request. The project uses poetry
.
$ poetry install --extras image
You can run the tests with poetry run pytest
. We use pytest-minecraft
to run tests against actual Minecraft releases.
$ poetry run pytest
$ poetry run pytest --minecraft-latest
We also use pytest-insta
for snapshot testing. Data pack and resource pack snapshots make it easy to monitor and review changes.
$ poetry run pytest --insta review
The project must type-check with pyright
. If you're using VSCode the pylance
extension should report diagnostics automatically. You can also install the type-checker locally with npm install
and run it from the command-line.
$ npm run watch
$ npm run check
The code follows the black
code style. Import statements are sorted with isort
.
$ poetry run isort beet tests
$ poetry run black beet tests
$ poetry run black --check beet tests