Blocks and Multiblocks

Blocks and Multiblocks

Butterfly API provides direct block registration helpers, a configurable block builder, and helpers for creating multiblock structures.

Block Builder

Use MOD.blockBuilder(...) when a block needs more control than normal registration provides.

import moth.butterflyapi.block.BlockRegistration;
import net.minecraft.block.Block;

public static final BlockRegistration<Block> DISPLAY_CASE =
        MOD.blockBuilder(
                "display_case",
                settings -> new Block(
                        settings
                                .strength(1.0F)
                                .nonOpaque()
                )
        )
        .itemSettings(settings -> settings.maxCount(16))
        .register();

register() returns a BlockRegistration containing the registered block and its item.

Block Without an Item

Use .noItem() when the block should not have a matching inventory item.

public static final BlockRegistration<Block> TECHNICAL_MARKER =
        MOD.blockBuilder(
                "technical_marker",
                settings -> new Block(
                        settings
                                .noCollision()
                                .nonOpaque()
                )
        )
        .noItem()
        .register();

Custom Block Item

Use .itemFactory(...) when the block needs a custom block item.

import net.minecraft.item.BlockItem;

public static final BlockRegistration<Block> DISPLAY_CASE =
        MOD.blockBuilder(
                "display_case",
                DisplayCaseBlock::new
        )
        .itemFactory(block -> new BlockItem(
                block,
                MOD.itemSettings("display_case").maxCount(1)
        ))
        .register();

Tall Block Items

Blocks such as doors or other tall structures can use a TallBlockItem.

public static final BlockRegistration<TallCrystalBlock> TALL_CRYSTAL =
        MOD.blockBuilder(
                "tall_crystal",
                TallCrystalBlock::new
        )
        .tallBlockItem()
        .register();

Multiblock Shapes

Butterfly API includes several built-in multiblock shapes:

MultiblockShape.ONE_BY_THREE_BY_ONE
MultiblockShape.ONE_BY_FOUR_BY_ONE
MultiblockShape.TWO_BY_TWO_BY_TWO
MultiblockShape.TWO_BY_ONE_BY_TWO

These describe the dimensions and individual parts of a multiblock structure.

AbstractMultiblockBlock

For standard multiblock behavior, extend AbstractMultiblockBlock.

import moth.butterflyapi.block.multiblock.AbstractMultiblockBlock;
import moth.butterflyapi.block.multiblock.MultiblockShape;
import net.minecraft.block.AbstractBlock;

public final class TallCrystalBlock
        extends AbstractMultiblockBlock {

    public TallCrystalBlock(AbstractBlock.Settings settings) {
        super(
                MultiblockShape.ONE_BY_THREE_BY_ONE,
                settings
        );
    }
}

Register it normally:

public static final TallCrystalBlock TALL_CRYSTAL =
        MOD.block(
                "tall_crystal",
                TallCrystalBlock::new
        );

Stored Part Information

AbstractMultiblockBlock stores the following information in its blockstate:

• Horizontal facing
• Part X
• Part Y
• Part Z

These values identify where each placed block belongs inside the complete structure.

Breaking Multiblocks

When one part of an AbstractMultiblockBlock structure is removed, Butterfly removes the remaining pieces without causing duplicate drops.

If neighbor updates leave incomplete pieces behind, orphaned pieces automatically clean themselves up.

Custom Multiblock Placement

For blocks that need custom behavior, use MultiblockPlacement directly.

Check Placement

boolean canPlace =
        MultiblockPlacement.canPlace(
                world,
                origin,
                facing,
                shape,
                context
        );

Find a Part Position

BlockPos partPos =
        MultiblockPlacement.partPos(
                origin,
                facing,
                part
        );

Find the Structure Origin

BlockPos origin =
        MultiblockPlacement.originOf(
                partPos,
                facing,
                part
        );

Block Resource Checklist

Common block resources include:

assets/<modid>/blockstates/<id>.json
assets/<modid>/models/block/<id>.json
assets/<modid>/textures/block/<id>.png

data/<modid>/loot_table/blocks/<id>.json
data/<modid>/recipe/<id>.json

Block Item Resources

Minecraft 1.21.11 block items normally need both item model layers:

assets/<modid>/items/<id>.json
assets/<modid>/models/item/<id>.json

Related Pages

• Registration
• Items
• Resource Conventions
• Troubleshooting