minestom-blocks

Minestom blocks

Block is an immutable, flyweight value. Block.GRASS_BLOCK, Block.OAK_STAIRS, etc. are shared constants; with* methods return new variants. Comparisons: block.compare(Block.STONE) (ignores nbt/handler by default).

Read / write in a world

instance.setBlock(0, 41, 0, Block.GOLD_BLOCK);
Block here = instance.getBlock(0, 41, 0);
if (here.isAir()) { /* ... */ }

setBlock/getBlock accept x,y,z or a Point. The chunk must be loaded; on an unloaded chunk reads return air and writes may be lost.

Block states (properties)

Stairs facing, slab type, redstone power, etc. are block states:

Block stairs = Block.OAK_STAIRS
    .withProperty("facing", "north")
    .withProperties(Map.of("half", "top", "waterlogged", "true"));

String facing = stairs.getProperty("facing");

Property names/values mirror vanilla blockstates. Wrong names throw — check the vanilla blockstate for that block.

Block NBT / data

Attach data (sign text, custom marker) — also immutable:

Block sign = Block.OAK_SIGN.withTag(Tag.String("custom_id"), "quest_giver");
instance.setBlock(x, y, z, sign);

See minestom-...tags concepts: Tag<T> is the typed accessor for NBT on blocks, items, and entities.

Block handlers (tile-entity behavior)

A BlockHandler gives a block server-side behavior + the block-entity id the client needs (chests, signs, skulls, spawners). Implement it for interactive/custom blocks:

public class MyChestHandler implements BlockHandler {
    @Override public Key getKey() { return Key.key("minecraft:chest"); }

    @Override public void onPlace(Placement placement) { /* ... */ }

    @Override public boolean onInteract(Interaction interaction) {
        interaction.getPlayer().sendMessage("opened");
        return true;
    }
}

Block chest = Block.CHEST.withHandler(new MyChestHandler());

Register handlers so saved/loaded blocks reattach them: MinecraftServer.getBlockManager().registerHandler(key, supplier). Without a registered handler, block entities load as plain blocks.

Handler interface method names (getKey/getNamespaceId, Placement/Interaction shapes) shift between releases — verify against https://javadoc.minestom.net for your version.

Bulk edits

For large region writes use the batch/generation path instead of per-block setBlock to avoid repeated chunk updates — see minestom-instances-worlds (Generator) and the batch docs.

Sources: https://minestom.net/docs/world/blocks, /docs/feature/tags, /docs/world/batch