Block Model Generation

A guide to generating block models and blockstates via datagen.

WARNING

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

PREREQUISITES

Make sure you've completed the datagen setup process first.

Setup

First, we will need to create our ModelProvider. Create a class that extends FabricModelProvider. Implement both abstract methods: generateBlockStateModels and generateItemModels. Lastly, create a constructor matching super.

java

public class ExampleModModelProvider extends FabricModelProvider {
	public ExampleModModelProvider(FabricDataOutput output) {
		super(output);
	}

	@Override
	public void generateBlockStateModels(BlockModelGenerators blockStateModelGenerator) {
	}

	@Override
	public void generateItemModels(ItemModelGenerators itemModelGenerator) {
	}

	@Override
	public String getName() {
		return "ExampleModModelProvider";
	}
}

Blockstates and Block Models

java

@Override
public void generateBlockStateModels(BlockStateModelGenerator blockStateModelGenerator) {
}

For block models, we will primarily be focusing on the generateBlockStateModels method. Notice the parameter BlockStateModelGenerator blockStateModelGenerator - this object will be responsible for generating all the JSON files. Here are some handy examples you can use to generate your desired models:

Simple Cube All

java

blockStateModelGenerator.createTrivialCube(ModBlocks.STEEL_BLOCK);

This is the most commonly used function. It generates a JSON model file for a normal cube_all block model. One texture is used for all six sides, in this case we use steel_block.

json

{
  "parent": "minecraft:block/cube_all",
  "textures": {
    "all": "example-mod:block/steel_block"
  }
}

It also generates a blockstate JSON file. Since we have no blockstate properties (e.g. Axis, Facing, ...), one variant is sufficient, and is used every time the block is placed.

json

{
  "variants": {
    "": {
      "model": "example-mod:block/steel_block"
    }
  }
}

Download 'Steel Block Texture'

Singletons

The registerSingleton method provides JSON model files based on the TexturedModel you pass in and a single blockstate variant.

java

blockStateModelGenerator.createTrivialBlock(ModBlocks.PIPE_BLOCK, TexturedModel.COLUMN_ALT);

This method will generate models for a normal cube, that uses the texture file pipe_block for the sides and the texture file pipe_block_top for the top and bottom sides.

json

{
  "parent": "minecraft:block/cube_column",
  "textures": {
    "end": "example-mod:block/pipe_block_top",
    "side": "example-mod:block/pipe_block"
  }
}

TIP

If you're stuck choosing which TextureModel you should use, open the TexturedModel class and look at the TextureMaps!

Download 'Pipe Block Textures'

Block Texture Pool

java

blockStateModelGenerator.family(ModBlocks.RUBY_BLOCK)
		.stairs(ModBlocks.RUBY_STAIRS)
		.slab(ModBlocks.RUBY_SLAB)
		.fence(ModBlocks.RUBY_FENCE);

Another useful method is registerCubeAllModelTexturePool: define the textures by passing in the "base block", and then append the "children", which will have the same textures. In this case, we passed in the RUBY_BLOCK, so the stairs, slab and fence will use the RUBY_BLOCK texture.

WARNING

It will also generate a simple cube all JSON model for the "base block" to ensure that it has a block model.

Be aware of this, if you're changing block model of this particular block, as it will result in en error.

You can also append a BlockFamily, which will generate models for all of its "children".

java

public static final BlockFamily RUBY_FAMILY =
		new BlockFamily.Builder(ModBlocks.RUBY_BLOCK)
		.stairs(ModBlocks.RUBY_STAIRS)
		.slab(ModBlocks.RUBY_SLAB)
		.fence(ModBlocks.RUBY_FENCE)
		.getFamily();

java

blockStateModelGenerator.family(ModBlocks.RUBY_BLOCK).generateFor(ModBlocks.RUBY_FAMILY);

Download 'Ruby Block Texture'

Doors and Trapdoors

java

blockStateModelGenerator.createDoor(ModBlocks.RUBY_DOOR);
blockStateModelGenerator.createTrapdoor(ModBlocks.RUBY_TRAPDOOR);
// blockStateModelGenerator.registerOrientableTrapdoor(ModBlocks.RUBY_TRAPDOOR);

Doors and trapdoors are a little different. Here, you have to make three new textures - two for the door, and one for the trapdoor.

The door:
- It has two parts - the upper half and the lower half. Each needs its own texture: in this case ruby_door_top for the upper half and ruby_door_bottom for the lower.
- The registerDoor() method will create models for all orientations of the door, both open and closed.
- You also need an item texture! Put it in assets/example-mod/textures/item/ folder.
The trapdoor:
- Here, you need only one texture, in this case named ruby_trapdoor. It will be used for all sides.
- Since TrapdoorBlock has a FACING property, you can use the commented out method to generate model files with rotated textures = the trapdoor will be "orientable". Otherwise, it will look the same no matter the direction it's facing.

Download 'Ruby Door and Trapdoor Textures'

Custom Block Models

In this section, we'll create the models for a Vertical Oak Log Slab, with Oak Log textures.

All fields and methods for this part of the tutorial are declared in a static inner class called CustomBlockStateModelGenerator.

Show CustomBlockStateModelGenerator

java

public static class CustomBlockStateModelGenerator {
	// :::custom-model
	public static final ModelTemplate VERTICAL_SLAB = block("vertical_slab", TextureSlot.BOTTOM, TextureSlot.TOP, TextureSlot.SIDE);

	//helper method for creating Models
	private static ModelTemplate block(String parent, TextureSlot... requiredTextureKeys) {
		return new ModelTemplate(Optional.of(ResourceLocation.fromNamespaceAndPath(ExampleMod.MOD_ID, "block/" + parent)), Optional.empty(), requiredTextureKeys);
	}

	//helper method for creating Models with variants
	private static ModelTemplate block(String parent, String variant, TextureSlot... requiredTextureKeys) {
		return new ModelTemplate(Optional.of(ResourceLocation.fromNamespaceAndPath(ExampleMod.MOD_ID, "block/" + parent)), Optional.of(variant), requiredTextureKeys);
	}

	// :::custom-model

	// :::custom-texture-map
	public static TextureMapping blockAndTopForEnds(Block block) {
		return new TextureMapping()
				.put(TextureSlot.TOP, ModelLocationUtils.getModelLocation(block, "_top"))
				.put(TextureSlot.BOTTOM, ModelLocationUtils.getModelLocation(block, "_top"))
				.put(TextureSlot.SIDE, ModelLocationUtils.getModelLocation(block));
	}

	// :::custom-texture-map

	// :::custom-supplier
	private static BlockModelDefinitionGenerator createVerticalSlabBlockStates(Block vertSlabBlock, ResourceLocation vertSlabId, ResourceLocation fullBlockId) {
		MultiVariant vertSlabModel = BlockModelGenerators.plainVariant(vertSlabId);
		MultiVariant fullBlockModel = BlockModelGenerators.plainVariant(fullBlockId);
		return MultiVariantGenerator.dispatch(vertSlabBlock)
				.with(PropertyDispatch.initial(VerticalSlabBlock.FACING, VerticalSlabBlock.SINGLE)
					.select(Direction.NORTH, true, vertSlabModel.with(BlockModelGenerators.UV_LOCK))
					.select(Direction.EAST, true, vertSlabModel.with(BlockModelGenerators.UV_LOCK).with(BlockModelGenerators.Y_ROT_90))
					.select(Direction.SOUTH, true, vertSlabModel.with(BlockModelGenerators.UV_LOCK).with(BlockModelGenerators.Y_ROT_180))
					.select(Direction.WEST, true, vertSlabModel.with(BlockModelGenerators.UV_LOCK).with(BlockModelGenerators.Y_ROT_270))
					.select(Direction.NORTH, false, fullBlockModel.with(BlockModelGenerators.UV_LOCK))
					.select(Direction.EAST, false, fullBlockModel.with(BlockModelGenerators.UV_LOCK))
					.select(Direction.SOUTH, false, fullBlockModel.with(BlockModelGenerators.UV_LOCK))
					.select(Direction.WEST, false, fullBlockModel.with(BlockModelGenerators.UV_LOCK))
				);
	}

	// :::custom-supplier

	// :::custom-gen
	public static void registerVerticalSlab(BlockModelGenerators generator, Block vertSlabBlock, Block fullBlock, TextureMapping textures) {
		ResourceLocation slabModel = VERTICAL_SLAB.create(vertSlabBlock, textures, generator.modelOutput);
		ResourceLocation fullBlockModel = ModelLocationUtils.getModelLocation(fullBlock);
		generator.blockStateOutput.accept(createVerticalSlabBlockStates(vertSlabBlock, slabModel, fullBlockModel));
		generator.registerSimpleItemModel(vertSlabBlock, slabModel);
	}

	// :::custom-gen
}

Custom Block Class

Create a VerticalSlab block with a FACING property and a SINGLE boolean property, like in the Block States tutorial. SINGLE will indicate if there are both slabs. Then you should override getOutlineShape and getCollisionShape, so that the outline is rendered correctly, and the block has the correct collision shape.

java

public static final VoxelShape NORTH_SHAPE = Block.box(0.0, 0.0, 0.0, 16.0, 16.0, 8.0);
public static final VoxelShape SOUTH_SHAPE = Block.box(0.0, 0.0, 8.0, 16.0, 16.0, 16.0);
public static final VoxelShape WEST_SHAPE = Block.box(0.0, 0.0, 0.0, 8.0, 16.0, 16.0);
public static final VoxelShape EAST_SHAPE = Block.box(8.0, 0.0, 0.0, 16.0, 16.0, 16.0);

java

@Override
protected VoxelShape getBlockSupportShape(BlockState state, BlockGetter world, BlockPos pos) {
	boolean type = state.getValue(SINGLE);
	Direction direction = state.getValue(FACING);
	VoxelShape voxelShape;

	if (type) {
		switch (direction) {
			case WEST -> voxelShape = WEST_SHAPE.singleEncompassing();
			case EAST -> voxelShape = EAST_SHAPE.singleEncompassing();
			case SOUTH -> voxelShape = SOUTH_SHAPE.singleEncompassing();
			case NORTH -> voxelShape = NORTH_SHAPE.singleEncompassing();
			default -> throw new MatchException(null, null);
		}

		return voxelShape;
	} else {
		return Shapes.block();
	}
}

@Override
protected VoxelShape getShape(BlockState state, BlockGetter world, BlockPos pos, CollisionContext context) {
	return this.getBlockSupportShape(state, world, pos);
}

@Override
protected VoxelShape getCollisionShape(BlockState state, BlockGetter world, BlockPos pos, CollisionContext context) {
	return this.getBlockSupportShape(state, world, pos);
}

Also override the canReplace() method, otherwise you couldn't make the slab a full block.

java

@Override
protected boolean canBeReplaced(BlockState state, BlockPlaceContext context) {
	Direction direction = state.getValue(FACING);

	if (context.getItemInHand().is(this.asItem()) && state.getValue(SINGLE)) {
		if (context.replacingClickedOnBlock()) {
			return context.getClickedFace().getOpposite() == direction;
		}
	}

	return false;
}

And you're done! You can now test the block out and place it in game.

Parent Block Model

Now, let's create a parent block model. It will determine the size, position in hand or other slots and the x and y coordinates of the texture. It's recommended to use an editor such as Blockbench for this, as making it manually is a really tedious process. It should look something like this:

json

{
  "parent": "minecraft:block/block",
  "textures": {
    "particle": "#side"
  },
  "display": {
    "gui": {
      "rotation": [
        30,
        -135,
        0
      ],
      "translation": [
        -1.5,
        0.75,
        0
      ],
      "scale": [
        0.625,
        0.625,
        0.625
      ]
    },
    "firstperson_righthand": {
      "rotation": [
        0,
        -45,
        0
      ],
      "translation": [
        0,
        2,
        0
      ],
      "scale": [
        0.375,
        0.375,
        0.375
      ]
    },
    "firstperson_lefthand": {
      "rotation": [
        0,
        315,
        0
      ],
      "translation": [
        0,
        2,
        0
      ],
      "scale": [
        0.375,
        0.375,
        0.375
      ]
    },
    "thirdperson_righthand": {
      "rotation": [
        75,
        -45,
        0
      ],
      "translation": [
        0,
        0,
        2
      ],
      "scale": [
        0.375,
        0.375,
        0.375
      ]
    },
    "thirdperson_lefthand": {
      "rotation": [
        75,
        315,
        0
      ],
      "translation": [
        0,
        0,
        2
      ],
      "scale": [
        0.375,
        0.375,
        0.375
      ]
    }
  },
  "elements": [
    {
      "from": [
        0,
        0,
        0
      ],
      "to": [
        16,
        16,
        8
      ],
      "faces": {
        "down": {
          "uv": [
            0,
            8,
            16,
            16
          ],
          "texture": "#bottom",
          "cullface": "down",
          "tintindex": 0
        },
        "up": {
          "uv": [
            0,
            0,
            16,
            8
          ],
          "texture": "#top",
          "cullface": "up",
          "tintindex": 0
        },
        "north": {
          "uv": [
            0,
            0,
            16,
            16
          ],
          "texture": "#side",
          "cullface": "north",
          "tintindex": 0
        },
        "south": {
          "uv": [
            0,
            0,
            16,
            16
          ],
          "texture": "#side",
          "tintindex": 0
        },
        "west": {
          "uv": [
            0,
            0,
            8,
            16
          ],
          "texture": "#side",
          "cullface": "west",
          "tintindex": 0
        },
        "east": {
          "uv": [
            8,
            0,
            16,
            16
          ],
          "texture": "#side",
          "cullface": "east",
          "tintindex": 0
        }
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174

See how blockstates are formatted for more information. Notice the #bottom, #top, #side keywords. They act as variables that can be set by models that have this one as a parent:

json

{
  "parent": "minecraft:block/cube_bottom_top",
  "textures": {
    "bottom": "minecraft:block/sandstone_bottom",
    "side": "minecraft:block/sandstone",
    "top": "minecraft:block/sandstone_top"
  }
}

The bottom value will replace the #bottom placeholder and so on. Put it in the resources/assets/example-mod/models/block/ folder.

Custom Model

Another thing we will need is an instance of the Model class. It will represent the actual parent block model inside our mod.

java

public static final ModelTemplate VERTICAL_SLAB = block("vertical_slab", TextureSlot.BOTTOM, TextureSlot.TOP, TextureSlot.SIDE);

//helper method for creating Models
private static ModelTemplate block(String parent, TextureSlot... requiredTextureKeys) {
	return new ModelTemplate(Optional.of(ResourceLocation.fromNamespaceAndPath(ExampleMod.MOD_ID, "block/" + parent)), Optional.empty(), requiredTextureKeys);
}

//helper method for creating Models with variants
private static ModelTemplate block(String parent, String variant, TextureSlot... requiredTextureKeys) {
	return new ModelTemplate(Optional.of(ResourceLocation.fromNamespaceAndPath(ExampleMod.MOD_ID, "block/" + parent)), Optional.of(variant), requiredTextureKeys);
}

The block() method creates a new Model, pointing to the vertical_slab.json file inside the resources/assets/example-mod/models/block/ folder. The TextureSlots represent the "placeholders" (#bottom, #top, ...) as an Object.

Using Texture Map

What does TextureMapping do? It actually provides the Resource Location that point to the textures. It technically behaves like a normal map - you associate a TextureSlot (Key) with a ResourceLocation (Value).

You can either use the vanilla ones, like TextureMapping.cube()(which associates all TextureKeys with the same Resource Location), or create a new one, by creating a new instance and then using .put() to associate keys with values.

TIP

TextureMapping.cube() associates all TextureSlots with the same Resource Location, no matter how many of them there are!

Since we want to use the Oak Log textures, but have the BOTTOM, TOP and SIDE TextureSlots, we need to create a new one.

java

public static TextureMapping blockAndTopForEnds(Block block) {
	return new TextureMapping()
			.put(TextureSlot.TOP, ModelLocationUtils.getModelLocation(block, "_top"))
			.put(TextureSlot.BOTTOM, ModelLocationUtils.getModelLocation(block, "_top"))
			.put(TextureSlot.SIDE, ModelLocationUtils.getModelLocation(block));
}

The bottom and top faces will use oak_log_top.png, the sides will use oak_log.png.

WARNING

All TextureSlots in the TextureMap have to match all TextureSlots in your parent block model!

Custom `BlockModelDefinitionGenerator` Method

The BlockModelDefinitionGenerator contains all blockstate variants, their rotation, and other options like UV lock.

java

private static BlockModelDefinitionGenerator createVerticalSlabBlockStates(Block vertSlabBlock, ResourceLocation vertSlabId, ResourceLocation fullBlockId) {
	MultiVariant vertSlabModel = BlockModelGenerators.plainVariant(vertSlabId);
	MultiVariant fullBlockModel = BlockModelGenerators.plainVariant(fullBlockId);
	return MultiVariantGenerator.dispatch(vertSlabBlock)
			.with(PropertyDispatch.initial(VerticalSlabBlock.FACING, VerticalSlabBlock.SINGLE)
				.select(Direction.NORTH, true, vertSlabModel.with(BlockModelGenerators.UV_LOCK))
				.select(Direction.EAST, true, vertSlabModel.with(BlockModelGenerators.UV_LOCK).with(BlockModelGenerators.Y_ROT_90))
				.select(Direction.SOUTH, true, vertSlabModel.with(BlockModelGenerators.UV_LOCK).with(BlockModelGenerators.Y_ROT_180))
				.select(Direction.WEST, true, vertSlabModel.with(BlockModelGenerators.UV_LOCK).with(BlockModelGenerators.Y_ROT_270))
				.select(Direction.NORTH, false, fullBlockModel.with(BlockModelGenerators.UV_LOCK))
				.select(Direction.EAST, false, fullBlockModel.with(BlockModelGenerators.UV_LOCK))
				.select(Direction.SOUTH, false, fullBlockModel.with(BlockModelGenerators.UV_LOCK))
				.select(Direction.WEST, false, fullBlockModel.with(BlockModelGenerators.UV_LOCK))
			);
}

First, we create a new BlockModelDefinitionGenerator using MultiVariantGenerator.dispatch(). Then we create a new PropertyDispatch that contains parameters for all variants of the block, in this case FACING and SINGLE, and pass it into the MultiVariantGenerator. Specify which model and which transformations (uvlock, rotation) are used when using .register(). For example:

Line 6: single slab facing north, so we'll use the model without rotation
Line 9: single slab facing west, so we'll rotate the model on the Y axis by 270°
Lines 10-13: non-single slab, which looks like a full block and we don't have to rotate it

Custom Datagen Method

The last step - creating an actual method you can call and that will generate the JSONs. But what are the parameters for?

BlockModelGenerators generator, the same one that got passed into generateBlockStateModels.
Block vertSlabBlock is the block to which we will generate the JSONs.
Block fullBlock - is the model used when the SINGLE property is false = the slab block looks like a full block.
TextureMapping textures defines the actual textures the model uses. See the Using Texture Map chapter.

java

public static void registerVerticalSlab(BlockModelGenerators generator, Block vertSlabBlock, Block fullBlock, TextureMapping textures) {
	ResourceLocation slabModel = VERTICAL_SLAB.create(vertSlabBlock, textures, generator.modelOutput);
	ResourceLocation fullBlockModel = ModelLocationUtils.getModelLocation(fullBlock);
	generator.blockStateOutput.accept(createVerticalSlabBlockStates(vertSlabBlock, slabModel, fullBlockModel));
	generator.registerSimpleItemModel(vertSlabBlock, slabModel);
}

First, we get the ResourceLocation of the single slab model with VERTICAL_SLAB.upload(). Then we get the ResourceLocation of the full block model with ModelLocationUtils.getModelLocation(), and pass those two models into createVerticalSlabBlockStates. The BlockStateSupplier gets passed into the blockStateCollector, so that the JSON files are actually generated. Also, we create a model for the vertical slab item with BlockModelGenerators.registerSimpleItemModel().

And that is all! Now all that's left to do is to call our method in our ModelProvider:

java

CustomBlockStateModelGenerator.registerVerticalSlab(
		blockStateModelGenerator,
		ModBlocks.VERTICAL_OAK_LOG_SLAB,
		Blocks.OAK_LOG,
		CustomBlockStateModelGenerator.blockAndTopForEnds(Blocks.OAK_LOG)
);

Sources and Links

You can view the example tests in Fabric API and this documentation's Example Mod for more information.

You can also find more examples of using custom datagen methods by browsing mods' open-source code, for example Vanilla+ Blocks and Vanilla+ Verticals by Fellteros.

Creating Your First Item

Block Entities

GUIs and Screens

Particles

Client Resources

Server Resources

Migrating Mappings

Page Authors

Files Referenced

Page Authors

Block Model Generation

Setup

Blockstates and Block Models

Simple Cube All

Singletons

Block Texture Pool

Doors and Trapdoors

Custom Block Models

Custom Block Class

Parent Block Model

Custom Model

Using Texture Map

Custom `BlockModelDefinitionGenerator` Method

Custom Datagen Method

Sources and Links

Page Authors

Files Referenced

Page Authors

Block Model Generation ​

Setup ​

Blockstates and Block Models ​

Simple Cube All ​

Singletons ​

Block Texture Pool ​

Doors and Trapdoors ​

Custom Block Models ​

Custom Block Class ​

Parent Block Model ​

Custom Model ​

Using Texture Map ​

Custom BlockModelDefinitionGenerator Method ​

Custom Datagen Method ​

Sources and Links ​

Block Model Generation

Setup

Blockstates and Block Models

Simple Cube All

Singletons

Block Texture Pool

Doors and Trapdoors

Custom Block Models

Custom Block Class

Parent Block Model

Custom Model

Using Texture Map

Custom `BlockModelDefinitionGenerator` Method

Custom Datagen Method

Sources and Links