Mecha
A powerful Minecraft command library.
from mecha import Mecha
mc = Mecha()
function = """
execute
as @a # For each "player",
at @s # start at their feet.
anchored eyes # Looking through their eyes,
facing 0 0 0 # face perfectly at the target
anchored feet # (go back to the feet)
positioned ^ ^ ^1 # and move one block forward.
rotated as @s # Face the direction the player
# is actually facing,
positioned ^ ^ ^-1 # and move one block back.
if entity @s[distance=..0.6] # Check if we're close to the
# player's feet.
run
say I'm facing the target!
"""
ast = mc.parse(function, multiline=True)
print(mc.serialize(ast)) # execute as @a at @s anchored eyes facing ...
Introduction
This package provides everything you need for working with Minecraft commands in Python, whether you're looking to process commands or build abstractions on top.
Features
- Extensible and version-agnostic
mcfunctionparser - Clean, immutable and hashable abstract syntax tree with source location
- Command config resolver that flattens and enumerates all the valid command prototypes
- Powerful rule dispatcher for processing specific ast nodes
- Composable ast visitors and reducers
- Comes with useful syntactic extensions like relative locations, nesting and implicit execute
- Compile-time scripting with Bolt, a subset of Python integrated into command syntax
- Rich function analyzer for keeping track of command statistics
- Execute arbitrary compilation passes in your
beetpipeline - (soon) Expressive command API for writing commands in Python
Credits
- A few test cases are adapted from
SPYGlass - Multiline example by
AjaxGb(MCC discord) - Multiline syntax derived from the
hangmanplugin - Partially inspired by
Trident
Installation
We recommend uv (https://github.com/astral-sh/uv#installation). With uv installed, you can try mecha by running uvx mecha. You can also install mecha as a global tool on your machine.
$ uv tool install mecha
If you see the message
warning: ... is not on your PATH, you'll need to add the specified directory to your global path to invokemechadirectly instead of usinguvx mecha.
You can make sure that mecha was successfully installed by trying to use the command-line utility.
$ mecha --help
Command-line utility
$ mecha --help
Usage: mecha [OPTIONS] [SOURCE]...
Validate data packs and .mcfunction files.
Options:
-m, --minecraft VERSION Minecraft version.
-l, --log LEVEL Configure output verbosity.
-s, --stats Collect statistics.
-j, --json FILENAME Output json.
-v, --version Show the version and exit.
-h, --help Show this message and exit.
You can use the command-line utility to check data packs and function files for errors. The command arguments can be zipped and unzipped data packs, individual function files, and if you specify a directory that's not a data pack it will recursively grab all the .mcfunction files in the directory. You can use the --minecraft option to select between versions 1.16, 1.17, and 1.18.
$ mecha path/to/my_data_pack
Validating with mecha vX.X.X
ERROR | mecha Expected curly '}' but got bracket ']'.
| path/to/my_data_pack/data/demo/functions/foo.mcfunction:5:34
| 4 |
| 5 | say hello @a[scores={foo=1, bar=2]
| : ^
Error: Reported 1 error.
The --stats option will output a report that shows how many commands, selectors and scoreboards were used. You can also use the --json option to output the raw statistics in a json file.
INFO | stats Analyzed 1 function
| -------------------------------------------------------------------------------
| Total commands (1 behind execute) | 4
| -------------------------------------------------------------------------------
| /scoreboard | 3
| objectives add <objective> <criteria> | 1
| players set <targets> <objective> <score> | 1
| players operation <targets> <targetObjective> <o... | 1
| /setblock (1 behind execute) | 1
| /execute | 1
| if score <target> <targetObjective> matches <range>... | 1
| as <targets> <subcommand> | 1
| run <subcommand> | 1
| -------------------------------------------------------------------------------
| Total selectors | 3
| -------------------------------------------------------------------------------
| @e | 2
| [tag] | 2
| [scores] | 1
| @s | 1
| @e with missing or inverted type | 2
| -------------------------------------------------------------------------------
| Scoreboard objectives | 2
| -------------------------------------------------------------------------------
| my_consts (dummy) | 3
| 10 | 2
| foo | 3
Github action
You can use mecha to check your data packs and function files for errors without having to install anything using the mcbeet/check-commands github action.
# .github/workflows/check-commands.yml
name: Check commands
on: [push]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: mcbeet/check-commands@v1
with:
source: .
This allows you to make sure that your commands don't contain any error when you push to your repository. For more details check out the action README.
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 uv.
$ uv sync
You can run the tests with uv run pytest.
$ uv run pytest
The code is formatted and checked with ruff.
$ uv run ruff format
$ uv run ruff check
License - MIT
1 maintainer
Release files for mecha 0.106.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mecha-0.106.0.tar.gz | 650.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mecha-0.106.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.3 MB
Release files / mecha-0.106.0.tar.gz
| Download URL | mecha-0.106.0.tar.gz |
|---|---|
| Size | 650.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c01042067600e0dd6752d954519a31ef4a0772e7ae51a0457bbe8c4639844c22
|
|
BLAKE2b-256 checksum How to use checksums |
88ae3364f83d380c10014a66a4da75cf11b6d0593fc4f753347cbdc9c46d7193
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mecha-0.106.0-py3-none-any.whl
| Download URL | mecha-0.106.0-py3-none-any.whl |
|---|---|
| Size | 687.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a71ae0242f5eaa37918f9fdc510c14913a2416ebf1bd0ce1642f44516cdd3121
|
|
BLAKE2b-256 checksum How to use checksums |
d3765e66471009c56b231687a607184e87537aae21ffa811767d5d94e85ee24f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
