mecha 0.103.0

A powerful Minecraft command library

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 mcfunction parser
• 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 beet pipeline
• (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 hangman plugin
• 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 invoke mecha directly instead of using uvx 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