{"id":15136224,"url":"https://github.com/simon816/command-block-assembly","last_synced_at":"2025-04-10T00:18:52.963Z","repository":{"id":53299443,"uuid":"90893865","full_name":"simon816/Command-Block-Assembly","owner":"simon816","description":"Compile high-level code into Minecraft commands","archived":false,"fork":false,"pushed_at":"2021-01-24T00:21:28.000Z","size":556,"stargazers_count":278,"open_issues_count":4,"forks_count":28,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-10T00:18:51.419Z","etag":null,"topics":["assembly","c","command-block","compiler","hacktoberfest","minecraft","redstone"],"latest_commit_sha":null,"homepage":"https://www.simon816.com/minecraft/assembler","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/simon816.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-10T18:03:01.000Z","updated_at":"2025-02-12T18:35:28.000Z","dependencies_parsed_at":"2022-08-13T02:31:03.014Z","dependency_job_id":null,"html_url":"https://github.com/simon816/Command-Block-Assembly","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simon816%2FCommand-Block-Assembly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simon816%2FCommand-Block-Assembly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simon816%2FCommand-Block-Assembly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simon816%2FCommand-Block-Assembly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simon816","download_url":"https://codeload.github.com/simon816/Command-Block-Assembly/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131371,"owners_count":21052827,"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":["assembly","c","command-block","compiler","hacktoberfest","minecraft","redstone"],"created_at":"2024-09-26T06:04:37.064Z","updated_at":"2025-04-10T00:18:52.919Z","avatar_url":"https://github.com/simon816.png","language":"Python","readme":"Command Block Assembly\n======================\n\nCommand Block Assembly started off as a tool that compiled assembly instructions\ninto Minecraft commands.\n\nIt has now grown into a much larger suite of tools for compiling source code into Minecraft\ncommands, therefore the toolchain as a whole is known as the Minecraft Compiler Collection (MCC).\n\n\nMinecraft Compiler Collection\n=============================\n\nThe Minecraft Compiler Collection (MCC) is an umbrella tool composed of multiple compilers in a toolchain to\ncompile high level code into Minecraft commands. It shares some similarities with the [GNU Compiler Collection](https://gcc.gnu.org/).\n\nMCC is composed of the following components:\n\n## CBL Compiler\n\nCommand Block Language (CBL) is a C++ inspired programming language specifically designed for Minecraft commands.\n\nCBL has been designed to abstract away from commands to the point where you don't need to consider the underlying mechanics.\n\nThe syntax is similar to C++ in a lot of ways. It also takes from Java's idea of having no pointers in the language.\n\n### Example\n\n```cpp\ninclude \"Text\"\n\ntype point {\n    int x;\n    int y;\n\n    constructor(int x, int y) {\n        this.x = x;\n        this.y = y;\n    }\n\n    inline point operator +(point other) {\n        return point(this.x + other.x, this.y + other.y);\n    }\n\n    inline point operator *(int val) {\n        return point(this.x * val, this.y * val);\n    }\n\n    inline void print();\n}\n\ninline void point::print() {\n    Text output;\n    output += \"(\";\n    output.append_ref(this.x);\n    output += \", \";\n    output.append_ref(this.y);\n    output += \")\";\n    output.send_to_all();\n}\n\nvoid main() {\n    point p1(2, 4);\n    point p2(5, 9);\n    p1 += p2;\n    p1 *= 2;\n    p1.print();\n}\n```\n\nThis example demonstrates several language features of CBL, some of which should be familiar to C++ programmers.\n\nBecause everything in this example can be determined statically (at compile time), the output is just:\n\n```mcfunction\ntellraw @a [{\"text\":\"(\"},{\"text\":\"14\"},{\"text\":\", \"},{\"text\":\"26\"},{\"text\":\")\"}]\n```\n\n### Documentation\n\nSee the [CBL Wiki](https://github.com/simon816/Command-Block-Assembly/wiki/CBL) for more details on the CBL language.\n\n## Assembler\n\nThe assembler in MCC is the original assembler when this project was just Command Block Assembly.\n\n### Assembly Language\n\nThe assembly language is simple and has instructions similar to x86.\n\nThe language looks like the following:\n\n```asm\n#include foo.asm\n\n; Useful comment\n\n.my_const #1 ; A constant value\n.my_ref my_const ; A constant reference\n\nmain:\n    MOV #0x01, 0 ; Do the thing\n    _loop: ADD my_const, 0\n    JMP _loop\n```\n\n### Example\n\nThe first example code written for CBA was an assembly program that prints the fibinacci sequence until\nthe next value overflows:\n\n```asm\n.x 0x00\n.y 0x01\n.old_x 0x02\n.counter 0x03\n\nmain:\n    MOV #0, x\n    MOV #1, y\n    MOV #1, counter\n    _loop:\n    PRINT \"fib(\", counter, \") = \", x\n    SYNC\n    ADD #1, counter\n    MOV x, old_x\n    MOV y, x\n    ADD old_x, y\n    CMP #0, x\n    JGE _loop ; if not \u003e=0 then x has overflowed\n```\n\n### Documentation\n\nThe instruction set and how write CBA programs is documented [on the wiki](https://github.com/simon816/Command-Block-Assembly/wiki/Assembly-Language).\n\n## C Compiler\n\nMCC partially implements a C compiler, most language features are implemented and it includes a preprocessor.\n\nThe C compiler sits on top of the assembler - all C code is compiled into assembly which is then passed through MCC's assembler.\n\n### Example\n\nHere is the same fibinacci sequence program but implemented in C:\n\n```c\n#include \u003cstdio.h\u003e\n\nint x;\nint y;\nint old_x;\nint counter;\n\nvoid main() {\n    x = 0;\n    y = 1;\n    counter = 1;\n    do {\n        printf(\"fib(%d) = %d\", counter++, x);\n        sync;\n        old_x = x;\n        x = y;\n        y += old_x;\n    } while(x \u003e= 0);\n}\n```\n\n### Documentation\n\nThe C compiler tries to stay as close as possible to the real C language, so documentation for most language features can be found elsewhere.\n\n\nThere is only one built-in type, `int`. Fundamentally, all data is stored in a scoreboard objective\nwhich is a 32 bit signed integer.\n\n\nThe [mclib.h](https://github.com/simon816/Command-Block-Assembly/blob/master/c_comp/include/mclib.h) file\ncontains several useful macros and definitions.\n\n\nBrowse the code in the [examples](https://github.com/simon816/Command-Block-Assembly/tree/master/examples) directory to see working examples\nof C code.\n\n\n## Command IR Compiler\n\nCommand IR is _the_ intermediate representation used by MCC. All compilers above ultimately generate Command IR code.\n\nIt is designed to relate closely to Minecraft commands themselves but provide a level of abstraction and context which\nenables optimizations among other things.\n\nCommand IR supports linking, which means it's possible to write code in CBL, C, ASM and IR directly and compile them\ntogether into one program.\n\n### Example\n\nHere is a hello world program:\n```\nfunction hello {\n    preamble {\n        $all_players = selector a\n        $message = text\n        extern\n    }\n\n    compiletime {\n        entry:\n        text_append $message, \"Hello, \"\n        text_append $message, \"World!\"\n    }\n\n    begin:\n    text_send $message, $all_players\n    ret\n}\n```\n\nThe output is a file `hello.mcfunction`:\n```mcfunction\ntellraw @a [{\"text\":\"Hello, \"},{\"text\":\"World!\"}]\n```\n\n### Documentation\n\nCommand IR's syntax, instruction reference and internal working is documented [on the wiki](https://github.com/simon816/Command-Block-Assembly/wiki/Command-IR).\n\n## Datapack Packer\n\nFinally, to bring everything together and generate a [datapack](https://minecraft.gamepedia.com/Data_pack), MCC reads a \"Datapack Definition\" file\nwhich declares how to package the code into a datapack.\n\nThe file is a simple INI file declaring attributes such as the namespace.\n\nTo complete the fibinacci example, the datapack definition file [`fib.dpd`](https://github.com/simon816/Command-Block-Assembly/blob/master/examples/fib.dpd) is:\n```ini\n[Datapack]\nnamespace=fib\nplace location=0 56 0\ndescription = An example datapack that prints the fibonacci sequence\n```\n\n### Documentation\n\nCurrently there is only one section in a DPD file, the **Datapack** section.\n\nIn order to create a datapack, two values are required: the `namespace` and the `place location`\n\n|Option|Description|\n|------|-----------|\n|namespace|The [namespace](https://minecraft.gamepedia.com/Namespaced_ID) used for functions in the datapack|\n|place location|An absolute position in the world to place the utility command block. Specifiy as 3 space-separated numbers|\n|spawn location|A position in the world to spawn the global armorstand. Specifiy as 3 space-separated components. Relative positioning (~) is allowed|\n|description|Set the description of the datapack|\n|generate cleanup|Generate a function which will remove everything created by the datapack|\n\n# MCC pipeline\n\nThere are 3 main stages to the compiler pipeline:\n1) Compiling: Converts source code into Command IR\n2) Linking: Merges one or more Command IR files into one master file\n3) Packing: Converts Command IR into Minecraft commands and creates a datapack from a datapack definition file\n\nThe MCC command takes a list of files, each code file goes through some number of transformations to end up as a Command IR object.\n\nThe linker merges each Command IR object into a single Command IR object. Any conflicts when merging will abort the compiler.\n\nA datapack definition file is required for the packer. The packer takes the single Command IR object and generates the final\nmcfunction files.\n\nTo get an idea of the hierarchy of components, here is a diagram:\n\n```\n            +---------------+\n            |               |\n            |  C Compiler   |\n            |               |\n+-----------+---------------+\n|           |               |\n|    CBL    |   Assembler   |\n|           |               |\n+-----------+---------------+\n|                           |\n|        Command IR         |\n|                           |\n+---------------------------+----+\n|                                |\n|      Command Abstraction       |       +--------------+\n+--------------------------------+-------|   Datapack   |\n|          Minecraft Commands            |  Definition  |\n+----------------------------------------+--------------+\n|                           Datapack                    |\n+-------------------------------------------------------+\n\n```\n\n# Running MCC\n\nYou will need to generate the standalone parsers (from [Lark](https://github.com/lark-parser/lark)) using the `./build-parsers.sh` script.\nIf on Windows, run the `python` commands in that script from the root of this project.\n\nThe Lark python package needs to be installed, `pip` can be used on the `requirements.txt` file. It is recommended to use `virtualenv`.\n\nExample: `virtualenv env --python=python3 \u0026\u0026 source env/bin/activate \u0026\u0026 pip install -r requirements.txt`\nOnce the parsers have been built, you don't technically need the virtual environment anymore. It can be deleted with\n`deactivate \u0026\u0026 rm -rf env/`\n\nAlternatively, you don't need to create the standalone parsers if you keep Lark available in the python environment.\n\nMCC is implemented in python. Currently it is not bundled into an executable so it must be invoked using the python interpreter.\n\nMCC is invoked by `python mcc.py` (If python 3 is not your default python command then run `python3 mcc.py`).\n\nCommand help text:\n```\nusage: mcc.py [-h] [-o outfile] [-E] [-c] [-S] [-dump-asm] [-O {0,1}]\n              [-dump-ir] [-shared] [--dummy-datapack] [--stats]\n              [--dump-commands] [--c-page-size SIZE]\n              infile [infile ...]\n\nCommand line tool for the Minecraft Compiler Collection\n\npositional arguments:\n  infile              Input files\n\noptional arguments:\n  -h, --help          show this help message and exit\n\nOutput generation control:\n  Options that control what stage in the output pipeline the compiler should\n  stop at.\n\n  -o outfile          Set the filename to write output to.\n  -E                  Stop after running the preprocessor. Input files which\n                      do not pass through a preprocessor are ignored.\n  -c                  Compile source files, but do not link. An object file is\n                      created for each source file\n  -S                  Do not compile Command IR code. A Command IR file is\n                      created for each non Command IR source file\n\nC Compiler options:\n  Options specific to the C compiler.\n\n  -dump-asm           Print The generated ASM code to stdout. Compilation is\n                      stopped after this point.\n\nOptimization control:\n  -O {0,1}            Control optimization level\n\nLinker arguments:\n  Arguments that control how the linker behaves.\n\n  -dump-ir            Print Command IR textual representation to stdout after\n                      linking objects, then exit\n\nPacker arguments:\n  Arguments that control how the packer behaves.\n\n  -shared             Include a symbol table and other metadata to enable\n                      dynamic linking of datapacks\n  --dummy-datapack    Don't write an output datapack. This can be used for\n                      debugging with --dump-commands\n  --stats             Print statistics about the generated datapack\n  --dump-commands     Dump the commands to stdout as they are written to the\n                      datapack\n  --c-page-size SIZE  Size of the memory page to generate if using the C\n                      compiler\n```\n\nMCC will dispatch a different tool depending on what the file extension of each input file is:\n\n * `.cbl` Will compile the CBL source code file\n * `.c` Will compile the C source code file\n * `.asm` Will compile the assembly file\n * `.ir` Will read the Command IR file\n * `.o` Will load the pre-compiled Command IR object file\n * `.dpd` Will read the datapack definition file\n\nDepending on the command line arguments, MCC will perform different tasks on each file. Some files\nare ignored if they are not relevant for the desired action.\n\n## Examples\n\nCompiling `examples/fib.asm` into a datapack `fib.zip`:\n```\npython mcc.py examples/fib.asm examples/fib.dpd\n```\n\nCompiling `examples/hdd_driver.c` into Command IR `examples/hdd_driver.ir`:\n```\npython mcc.py examples/hdd_driver.c -S\n```\n\nCompiling `mylib.cbl` into an object file, statically linking `myprogram.cbl` with the object and `examples/fib.ir`,\nthen using `mydatapack.dpd` to create `mysuperdatapack.zip`:\n```\npython mcc.py mylib.cbl -c\npython mcc.py mylib.o myprogram.cbl examples/fib.ir mydatapack.dpd -o mysuperdatapack.zip\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimon816%2Fcommand-block-assembly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimon816%2Fcommand-block-assembly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimon816%2Fcommand-block-assembly/lists"}