Block Entity Renderers

Sometimes, using Minecraft's model format is not enough. If you need to add dynamic rendering to your block's visuals, you will need to use a BlockEntityRenderer.

For example, let's make the Counter Block from the Block Entities article show the number of clicks on its top side.

Creating a BlockEntityRenderer

Block entity rendering uses a submit/render system where you first submit the data required to render an object to the screen, the game then renders the object using it's submitted state.

When creating a BlockEntityRenderer for the CounterBlockEntity, it's important to place the class in the appropriate source set, such as src/client/, if your project uses split source sets for client and server. Accessing rendering-related classes directly in the src/main/ source set is not safe because those classes might be loaded on a server.

First, we need to create a BlockEntityRenderState for our CounterBlockEntity to hold the data that will be used for rendering. In this case, we will need the clicks to be available during rendering.

public class CounterBlockEntityRenderState extends BlockEntityRenderState {
	private int clicks = 0;

	public int getClicks() {
		return clicks;
	}

	public void setClicks(int clicks) {
		this.clicks = clicks;
	}
}

Then we create a BlockEntityRenderer for our CounterBlockEntity.

public class CounterBlockEntityRenderer implements BlockEntityRenderer<CounterBlockEntity, CounterBlockEntityRenderState> {
	public CounterBlockEntityRenderer(BlockEntityRendererProvider.Context context) {
	}

	@Override
	public CounterBlockEntityRenderState createRenderState() {
		return new CounterBlockEntityRenderState();
	}

	@Override
	public void extractRenderState(CounterBlockEntity blockEntity, CounterBlockEntityRenderState state, float tickProgress, Vec3 cameraPos, @Nullable ModelFeatureRenderer.CrumblingOverlay crumblingOverlay) {
	}

	@Override
	public void submit(CounterBlockEntityRenderState state, PoseStack matrices, SubmitNodeCollector queue, CameraRenderState cameraState) {
	}
}

The new class has a constructor with BlockEntityRendererProvider.Context as a parameter. The Context has a few useful rendering utilities, like the ItemRenderer or Font. Also, by including a constructor like this, it becomes possible to use the constructor as the BlockEntityRendererProvider functional interface itself:

public class ExampleModBlockEntityRenderer implements ClientModInitializer {
	@Override
	public void onInitializeClient() {
		BlockEntityRenderers.register(ModBlockEntities.COUNTER_BLOCK_ENTITY, CounterBlockEntityRenderer::new);
	}
}

We will override a few methods to set up the render state along with the submit method where the rendering logic will be set up.

createRenderState can be used to initialize the render state.

@Override
public CounterBlockEntityRenderState createRenderState() {
	return new CounterBlockEntityRenderState();
}

extractRenderState can be used to update the render state with entity data.

@Override
public void extractRenderState(CounterBlockEntity blockEntity, CounterBlockEntityRenderState state, float tickProgress, Vec3 cameraPos, @Nullable ModelFeatureRenderer.CrumblingOverlay crumblingOverlay) {
	// :::1
	BlockEntityRenderer.super.extractRenderState(blockEntity, state, tickProgress, cameraPos, crumblingOverlay);
	state.setClicks(blockEntity.getClicks());
	// :::1
}

You should register block entity renderers in your ClientModInitializer class.

BlockEntityRenderers is a registry that maps each BlockEntityType with custom rendering code to its respective BlockEntityRenderer.

Drawing on Blocks

Now that we have a renderer, we can draw. The submit method is called every frame, and it's where the rendering magic happens.

Moving Around

First, we need to offset and rotate the text so that it's on the block's top side.

INFO

As the name suggests, the PoseStack is a stack, meaning that you can push and pop transformations. A good rule-of-thumb is to push a new one at the beginning of the submit method and pop it at the end, so that the rendering of one block doesn't affect others.

More information about the PoseStack can be found in the Basic Rendering Concepts article.

To make the translations and rotations needed easier to understand, let's visualize them. In this picture, the green block is where the text would be drawn, by default in the furthest bottom-left point of the block:

So first we need to move the text halfway across the block on the X and Z axes, and then move it up to the top of the block on the Y axis:

This is done with a single translate call:

matrices.translate(0.5, 1, 0.5);

That's the translation done, rotation and scale remain.

By default, the text is drawn on the XY plane, so we need to rotate it 90 degrees around the X axis to make it face upwards on the XZ plane:

The PoseStack does not have a rotate function, instead we need to use mulPose and Axis.XP:

matrices.mulPose(Axis.XP.rotationDegrees(90));

Now the text is in the correct position, but it's too large. The BlockEntityRenderer maps the whole block to a [-0.5, 0.5] cube, while a Font uses Y coordinates of [0, 9]. As such, we need to scale it down by a factor of 18:

matrices.scale(1/18f, 1/18f, 1/18f);

Now, the whole transformation looks like this:

matrices.pushPose();
matrices.translate(0.5, 1, 0.5);
matrices.mulPose(Axis.XP.rotationDegrees(90));
matrices.scale(1/18f, 1/18f, 1/18f);

Drawing Text

As mentioned earlier, the Context passed into the constructor of our renderer has a Font that we can use to measure text (width), which is useful for centering.

To draw the text, we will be submitting the necessary data to the render queue. Since we're drawing some text, we can use the submitText method provided through the SubmitNodeCollector instance passed into the submit method.

String text = state.getClicks() + "";
float width = font.width(text);

// draw the text. params:
// text, x, y, color, ordered text, shadow, text layer type, light, color, background color, outline color
queue.submitText(
		matrices,
		-width / 2, -4f,
		Component.literal(text).getVisualOrderText(),
		false,
		Font.DisplayMode.SEE_THROUGH,
		state.lightCoords,
		0xffffffff,
		0,
		0
);

The submitText method takes a lot of parameters, but the most important ones are:

• the FormattedCharSequence to draw;
• its x and y coordinates;
• the RGB color value;
• the PoseStack describing how it should be transformed.

And after all this work, here's the result: