{"id":13817135,"url":"https://github.com/mcbeet/mecha","last_synced_at":"2025-04-05T11:07:27.587Z","repository":{"id":37058217,"uuid":"408662738","full_name":"mcbeet/mecha","owner":"mcbeet","description":"A powerful Minecraft command library.","archived":false,"fork":false,"pushed_at":"2025-03-27T19:59:22.000Z","size":2732,"stargazers_count":48,"open_issues_count":8,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-29T10:09:24.832Z","etag":null,"topics":["beet","datapack","mcfunction","minecraft","minecraft-commands"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcbeet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["vberlier"]}},"created_at":"2021-09-21T02:21:11.000Z","updated_at":"2025-03-27T19:59:25.000Z","dependencies_parsed_at":"2024-01-20T16:49:36.653Z","dependency_job_id":"d2981abf-4d10-4018-9b64-7d9fe3a2a4d6","html_url":"https://github.com/mcbeet/mecha","commit_stats":{"total_commits":881,"total_committers":9,"mean_commits":97.88888888888889,"dds":"0.45062429057888764","last_synced_commit":"d71353367ff1a7fd9e49587e6604268d8aba8695"},"previous_names":[],"tags_count":231,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcbeet%2Fmecha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcbeet%2Fmecha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcbeet%2Fmecha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcbeet%2Fmecha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcbeet","download_url":"https://codeload.github.com/mcbeet/mecha/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325693,"owners_count":20920714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beet","datapack","mcfunction","minecraft","minecraft-commands"],"created_at":"2024-08-04T06:00:34.954Z","updated_at":"2025-04-05T11:07:27.555Z","avatar_url":"https://github.com/mcbeet.png","language":"Python","funding_links":["https://github.com/sponsors/vberlier"],"categories":["Official"],"sub_categories":[],"readme":"\u003cimg align=\"right\" src=\"https://raw.githubusercontent.com/mcbeet/mecha/main/logo.png\" alt=\"logo\" width=\"76\"\u003e\n\n# Mecha\n\n[![GitHub Actions](https://github.com/mcbeet/mecha/workflows/CI/badge.svg)](https://github.com/mcbeet/mecha/actions)\n[![PyPI](https://img.shields.io/pypi/v/mecha.svg)](https://pypi.org/project/mecha/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mecha.svg)](https://pypi.org/project/mecha/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n[![Discord](https://img.shields.io/discord/900530660677156924?color=7289DA\u0026label=discord\u0026logo=discord\u0026logoColor=fff)](https://discord.gg/98MdSGMm8j)\n\n\u003e A powerful Minecraft command library.\n\n```python\nfrom mecha import Mecha\n\nmc = Mecha()\n\nfunction = \"\"\"\n    execute\n        as @a                        # For each \"player\",\n        at @s                        # start at their feet.\n        anchored eyes                # Looking through their eyes,\n        facing 0 0 0                 # face perfectly at the target\n        anchored feet                # (go back to the feet)\n        positioned ^ ^ ^1            # and move one block forward.\n        rotated as @s                # Face the direction the player\n                                     # is actually facing,\n        positioned ^ ^ ^-1           # and move one block back.\n        if entity @s[distance=..0.6] # Check if we're close to the\n                                     # player's feet.\n        run\n            say I'm facing the target!\n\"\"\"\n\nast = mc.parse(function, multiline=True)\nprint(mc.serialize(ast))  # execute as @a at @s anchored eyes facing ...\n```\n\n## Introduction\n\nThis package provides everything you need for working with Minecraft commands in Python, whether you're looking to process commands or build abstractions on top.\n\n### Features\n\n- Extensible and version-agnostic `mcfunction` parser\n- Clean, immutable and hashable abstract syntax tree with source location\n- Command config resolver that flattens and enumerates all the valid command prototypes\n- Powerful rule dispatcher for processing specific ast nodes\n- Composable ast visitors and reducers\n- Comes with useful syntactic extensions like relative locations, nesting and implicit execute\n- Compile-time scripting with [Bolt](https://github.com/mcbeet/bolt), a subset of Python integrated into command syntax\n- Rich function analyzer for keeping track of command statistics\n- Execute arbitrary compilation passes in your [`beet`](https://github.com/mcbeet/beet) pipeline\n- _(soon)_ Expressive command API for writing commands in Python\n\n## Credits\n\n- [A few test cases are adapted from `SPYGlass`](https://github.com/SPYGlassMC/SPYGlass)\n- [Multiline example by `AjaxGb` (MCC discord)](https://discord.com/channels/154777837382008833/157097006500806656/539318174466703361)\n- [Multiline syntax derived from the `hangman` plugin](https://github.com/mcbeet/beet/blob/main/beet/contrib/hangman.py)\n- [Partially inspired by `Trident`](https://energyxxer.com/trident/)\n\n## Installation\n\nThe package can be installed with `pip`.\n\n```bash\n$ pip install mecha\n```\n\n## Command-line utility\n\n```bash\n$ mecha --help\nUsage: mecha [OPTIONS] [SOURCE]...\n\n  Validate data packs and .mcfunction files.\n\nOptions:\n  -m, --minecraft VERSION  Minecraft version.\n  -l, --log LEVEL          Configure output verbosity.\n  -s, --stats              Collect statistics.\n  -j, --json FILENAME      Output json.\n  -v, --version            Show the version and exit.\n  -h, --help               Show this message and exit.\n```\n\nYou 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`.\n\n```bash\n$ mecha path/to/my_data_pack\nValidating with mecha vX.X.X\n\nERROR  | mecha  Expected curly '}' but got bracket ']'.\n       | path/to/my_data_pack/data/demo/functions/foo.mcfunction:5:34\n       |      4 |\n       |      5 |  say hello @a[scores={foo=1, bar=2]\n       |        :                                   ^\n\nError: Reported 1 error.\n```\n\nThe `--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.\n\n```\nINFO   | stats  Analyzed 1 function\n       | -------------------------------------------------------------------------------\n       | Total commands (1 behind execute)                                      |      4\n       | -------------------------------------------------------------------------------\n       |        /scoreboard                                                     |      3\n       |                    objectives add \u003cobjective\u003e \u003ccriteria\u003e               |      1\n       |                    players set \u003ctargets\u003e \u003cobjective\u003e \u003cscore\u003e           |      1\n       |                    players operation \u003ctargets\u003e \u003ctargetObjective\u003e \u003co... |      1\n       |        /setblock (1 behind execute)                                    |      1\n       |        /execute                                                        |      1\n       |                 if score \u003ctarget\u003e \u003ctargetObjective\u003e matches \u003crange\u003e... |      1\n       |                 as \u003ctargets\u003e \u003csubcommand\u003e                              |      1\n       |                 run \u003csubcommand\u003e                                       |      1\n       | -------------------------------------------------------------------------------\n       | Total selectors                                                        |      3\n       | -------------------------------------------------------------------------------\n       |        @e                                                              |      2\n       |           [tag]                                                        |      2\n       |           [scores]                                                     |      1\n       |        @s                                                              |      1\n       |        @e with missing or inverted type                                |      2\n       | -------------------------------------------------------------------------------\n       | Scoreboard objectives                                                  |      2\n       | -------------------------------------------------------------------------------\n       |        my_consts (dummy)                                               |      3\n       |                  10                                                    |      2\n       |        foo                                                             |      3\n```\n\n## Github action\n\nYou 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.\n\n```yml\n# .github/workflows/check-commands.yml\nname: Check commands\non: [push]\n\njobs:\n  check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v2\n      - uses: mcbeet/check-commands@v1\n        with:\n          source: .\n```\n\nThis 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).\n\n## Contributing\n\nContributions 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`](https://python-poetry.org/).\n\n```bash\n$ poetry install\n```\n\nYou can run the tests with `poetry run pytest`.\n\n```bash\n$ poetry run pytest\n```\n\nThe project must type-check with [`pyright`](https://github.com/microsoft/pyright). If you're using VSCode the [`pylance`](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) extension should report diagnostics automatically. You can also install the type-checker locally with `npm install` and run it from the command-line.\n\n```bash\n$ npm run watch\n$ npm run check\n```\n\nThe code follows the [`black`](https://github.com/psf/black) code style. Import statements are sorted with [`isort`](https://pycqa.github.io/isort/).\n\n```bash\n$ poetry run isort mecha tests\n$ poetry run black mecha tests\n$ poetry run black --check mecha tests\n```\n\n---\n\nLicense - [MIT](https://github.com/mcbeet/mecha/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcbeet%2Fmecha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcbeet%2Fmecha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcbeet%2Fmecha/lists"}