Minestom wiki
Search…
Blocks

Overview

A Block is an immutable object containing:
    Namespace & protocol id
    Map<String, String> containing properties (e.g. waterlogged)
    State id which is the numerical id defining the block visual used in chunk packets and a few others
    Optional nbt
    A BlockHandler
The immutability allows block references to be cached and reused.

Usage

1
Instance instance = ...;
2
// Each vanilla block has a constant visible from the `Block` interface
3
instance.setBlock(0, 40, 0, Block.STONE);
4
5
// Retrieve the tnt block and create a new block with the `unstable`
6
// property sets to "true".
7
// Property names are defined by Mojang and usable in various commands
8
Block tnt = Block.TNT.withProperty("unstable", "true");
9
instance.setBlock(0, 41, 0, tnt);
Copied!

Registry

Each block has unique data which can be retrieved with Block#registry().
1
Block block = Block.GRASS;
2
// Some fields have their own dedicated method
3
boolean solid = block.registry().isSolid();
4
// ... you can however retrieve them from string
5
double hardness = block.registry().getDouble("hardness");
6
hardness = block.registry().hardness();
Copied!

Tags

Block implements TagReadable meaning that they can contain all kinds of data. (see Tags)
1
Tag<String> tag = Tag.String("my-key");
2
Block tnt = Block.TNT;
3
// Create a new block with the tag sets to "my-value"
4
tnt = tnt.withTag(tag, "my-value");
5
// Retrieve the value from the newly created block
6
String value = tnt.getTag(tag);
7
8
// Block can also expose a convenient view of their nbt
9
NBTCompound nbt = tnt.nbt();
Copied!
Tags data can be serialized and will be saved on disk automatically.
Tags id, x, y, z and keepPackedare used by the anvil loader and may cause unexpected behavior when added to blocks.

Handlers

The BlockHandler interface allows blocks to have behavior by listening to some events like placement or interaction. And can be serialized to disk thanks to their namespace.
1
public class DemoHandler implements BlockHandler {
2
@Override
3
public void onPlace(@NotNull Placement placement) {
4
if (placement instanceof PlayerPlacement) {
5
// A player placed the block
6
}
7
Block block = placement.getBlock();
8
System.out.println("The block " + block.name() + " has been placed");
9
}
10
11
@Override
12
public @NotNull NamespaceID getNamespaceId() {
13
// Namespace required for serialization purpose
14
return NamespaceID.from("minestom:demo");
15
}
16
}
Copied!
You can then decide to use one handler per block, or share it with several.
1
Block tnt = Block.TNT;
2
// Create a new block with the specified handler.
3
// Be aware that block objects can be reused, handlers should
4
// therefore never assume to be assigned to a single block.
5
tnt = tnt.withHandler(new DemoHandler());
6
7
// Share the same handler reference with multiple blocks
8
BlockHandler handler = new DemoHandler();
9
Block stone = Block.STONE.withHandler(handler);
10
Block grass = Block.GRASS.withHandler(handler);
Copied!
Last modified 2mo ago