Transparency and Tinting 1.21.11

Learn how to manipulate the appearance of blocks and tint them dynamically.

WARNING

This page is written for version 1.21.11. Documentation for older versions may be incomplete.

You may sometimes want the appearance of blocks to be handled specially in-game. For example, some blocks may appear transparent, and some others may get a tint applied to them.

Let's take a look at how we can manipulate the appearance of a block.

For this example, let's register a block. If you are unfamiliar with this process, please read about block registration first.

public static final Block WAXCAP_BLOCK = Registry.register(
				BuiltInRegistries.BLOCK,
				Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "waxcap"),
				new Block(BlockBehaviour.Properties.of()
								.noCollision()
								.instabreak()
								.offsetType(BlockBehaviour.OffsetType.XYZ)
								.setId(WAXCAP_BLOCK_KEY)
				));

Make sure to add:

• A block state in /blockstates/waxcap.json
• A model in /models/block/waxcap.json
• A texture in /textures/block/waxcap.png

If everything is correct, you'll be able to see the block in-game. However, you'll notice that, when placed, the block doesn't look right.

This is because a texture with transparency will require a bit of additional setup.

Manipulating Block Appearance

Even if your block's texture is transparent or translucent, it will still appear opaque. To fix this, you need to set your block's Chunk Section Layer.

Chunk Section Layers are categories used to group different types of block surfaces for rendering. This allows the game to use the correct visual effects and optimizations for each type.

We need to register our block with the correct Chunk Section Layer. Vanilla provides the following options.

• SOLID: The default, a solid block without any transparency.
• CUTOUT and CUTOUT_MIPPED: A block that makes use of transparency, for example Glass or Flowers. CUTOUT_MIPPED will look better at a distance.
• TRANSLUCENT: A block that makes use of translucent (partially transparent) pixels, for example Stained Glass or Water.

Our example has transparency, so it will use CUTOUT.

In your client initializer, register your block with the correct ChunkSectionLayer using Fabric API's BlockRenderLayerMap.

BlockRenderLayerMap.putBlock(ExampleModAppearance.WAXCAP_BLOCK, ChunkSectionLayer.CUTOUT);

Now, your block should have proper transparency.

Block Color Providers

Even though our block looks fine in-game, its texture is grayscale. We could dynamically apply a color tint, like how vanilla Leaves change color based on biomes.

Fabric API provides ColorProviderRegistry to register a tint color provider, which we'll use to dynamically color the block.

Let's use this API to register a tint such that, when our Waxcap block is placed on grass, it will look green, otherwise it'll look brown.

In your client initializer, register your block to the ColorProviderRegistry, along with the appropriate logic.

ColorProviderRegistry.BLOCK.register((blockState, blockAndTintGetter, blockPos, i) -> {
	if (blockAndTintGetter != null && blockPos != null) {
		BlockState stateBelow = blockAndTintGetter.getBlockState(blockPos.below());

		if (stateBelow.is(Blocks.GRASS_BLOCK)) {
			return 0x98FB98; // Color code in hex format
		}
	}

	return 0xFFDAB9; // Color code in hex format
}, ExampleModAppearance.WAXCAP_BLOCK);

Now, the block will be tinted based on where its placed.