Home

Welcome to the documentation. Here you can find short references and examples on how to setup and use this library.

Note

In this wiki, everything between <> needs to be replaced with the appropriate value

🖥️Installation

To use this library you first need to install beet. You can take a look at their documentation on how to do that. (Go check it out, it's really cool!). It's best to familiarize yourself with beet before using this library.

Next you install the pypackage $pip install mcmultiblocks in your local beet envrionment.
After that you add the plugin to the beet pipeline:

"require": [
   "mcmultiblocks"
]

Now you should have successfully added multiblocks to your datapack. Let's get into using it!

🛠️Getting Started

Using this library is really easy due to our focus on development ease and portability.

Building your structure

To start, just build a normal structure and save it in a structure block as usual. Find the .nbt file in <your_world>/generated and move it into your datapack under <namespace>/structure. You can use structure voids in your structure inorder to make your multiblock ignore those spots. Air blocks will be required inorder for your multiblock to complete.

Generating the right files

The library makes use of a new json file in data/<namespace>/multiblock. You can find the complete file structure here

For example: data/tech_datapack/multiblock/industrial_furnace

{
    "id" : "industrial_furnace",
    "structure": "tech_datapack:multiblock/industrial_furnace",
    "anchor_mode": "center",
    "place_mode": "facing",
    "callback": {
        "on_place": "function tech_datapack:industrial_furnace/custom_block/summon_blueprint_markers",
        "on_complete": "say industrial furnace completed"
    },
    "conditions": [
        "function tech_datapack:industrial_furnace/custom_block/check_location"
    ]
}

Once you've successfully added your multiblock file, you can build your beet project. This will generate all the neccessary files so you can interact with your multiblock.

Warning

For some reason, windows has a file path length limit. This means that sometimes (when your blocks have many different blockstates) this limit can be reached although we have compressed the length already quite a lot.

If you're experiencing a bug where checks are not running correctly. Go take a look in your linked path and compare it to the build to see if all the files get properly copied over. When you've reached this limit, make a github issue and we'll see what we can do.

Spawning your multiblock

In order to summon an instance of your multiblock, you can run the function tag: #mtb-generated:<your_namespace>/<id_of_your_multiblock>/summon_instance. This will spawn the root marker, which from now on will be used to interact with this multiblock instance. In order to select the marker, use the selector @e[type=marker,tag=mtb.<namespace>-<multiblock_id>,tag=mtb.root.

Note

Depending on the placement mode you've chosen in the json file, the location of the marker may vary.

Now you've succesfully summoned, you can finally show the blueprint by running the function tag #mtb-generated:<namespace>/<multiblock_id>/blueprint/show as the root multiblock marker. This should summon all the block displays and item displays used as a schematic for the end user. It will also enable the blueprint block checking and show wrong blocks.

🪲 Debugging your multiblocks

This library also includes an extensive debugging feature so you can exactly see what's going on with your multiblock. Inorder to enable this feature, add the tag mtb.debug to yourself. After that you run a /reload command so the library detects it. (That way, we can optimize the debugging commands to a single score check when it's not enabled so we don't have much overhead.)

⚡Next steps

Now you know how to summon a basic multiblock, you can start customizing the behaviour of your multiblock using our built in user friendly functions. Take a look at the function reference or the examples folder

🫂Collaboration

Thanks for your interest in collaborating, we love your intent to improve this open source project.

All of our code is written in the pypackage folder in this repo. You can make a private beet project and import the plugin in order to test your code.

Inorder to setup a development environment:

1. Clone the repositiory
2. Make a virtual environment (Call it venv) inside the root folder (it's already added to the git ignore)
3. Download our development environment here
4. Unzip the folder and move it into the repository root (normally, all folders/files should already be added to the git ignore)

Now you have installed a beet project for development, link it to your world so you can test your changes ingame. If you're using visual studio code, you can run the task run_beet to build the project. It will also install all the requirements needed to run the project.

Warning

Fully AI generated Pull Requests won't be accepted