Metadata-Version: 2.3
Name: mecha
Version: 0.100.0b3
Summary: A powerful Minecraft command library
Keywords: beet,minecraft,datapack,minecraft-commands,mcfunction
Author: Valentin Berlier
Author-email: Valentin Berlier <berlier.v@gmail.com>
License: MIT License
         
         Copyright (c) 2021 Valentin Berlier
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Requires-Dist: beet>=0.113.0b4
Requires-Dist: tokenstream>=1.7.0
Requires-Python: >=3.14
Project-URL: Repository, https://github.com/mcbeet/beet/blob/main/packages/mecha
Description-Content-Type: text/markdown

<img align="right" src="https://raw.githubusercontent.com/mcbeet/beet/main/packages/mecha/logo.png" alt="logo" width="76">

# Mecha

[![GitHub Actions](https://github.com/mcbeet/beet/workflows/CI/badge.svg)](https://github.com/mcbeet/beet/actions)
[![PyPI](https://img.shields.io/pypi/v/mecha.svg)](https://pypi.org/project/mecha/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mecha.svg)](https://pypi.org/project/mecha/)
[![Discord](https://img.shields.io/discord/900530660677156924?color=7289DA&label=discord&logo=discord&logoColor=fff)](https://discord.gg/98MdSGMm8j)

> A powerful Minecraft command library.

```python
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](https://github.com/mcbeet/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`](https://github.com/mcbeet/beet) pipeline
- _(soon)_ Expressive command API for writing commands in Python

## Credits

- [A few test cases are adapted from `SPYGlass`](https://github.com/SPYGlassMC/SPYGlass)
- [Multiline example by `AjaxGb` (MCC discord)](https://discord.com/channels/154777837382008833/157097006500806656/539318174466703361)
- [Multiline syntax derived from the `hangman` plugin](https://github.com/mcbeet/beet/blob/main/beet/contrib/hangman.py)
- [Partially inspired by `Trident`](https://energyxxer.com/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.

```console
$ 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.

```console
$ mecha --help
```

## Command-line utility

```bash
$ 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`.

```bash
$ 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`](https://github.com/mcbeet/check-commands) github action.

```yml
# .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](https://github.com/mcbeet/check-commands#usage).

## 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`](https://github.com/astral-sh/uv).

```console
$ uv sync
```

You can run the tests with `uv run pytest`.

```console
$ uv run pytest
```

The code is formatted and checked with [`ruff`](https://github.com/astral-sh/ruff).

```console
$ uv run ruff format
$ uv run ruff check
```

---

License - [MIT](https://github.com/mcbeet/mecha/blob/main/packages/mecha/LICENSE)
