Skip to content

How to add a block in Fabric and NeoForge 1.21.1

To add a block in Minecraft 1.21.1, register the block and a block item in Java, then add six resource files: a blockstate, a block model, an item model, a 16 × 16 PNG texture, a loot table and an English name. A block that needs a pickaxe also needs two block tags, and a craftable one needs a recipe. In 1.21 the data folders became singular: loot_table, recipe and tags/block, so 1.20.x tutorials put those files in folders the game no longer reads.

Last checked on 3 November 2026. The code and files below are from a Fabric 1.21.1 project and a NeoForge 1.21.1 project with the mod id guidemod. Both built with ./gradlew build, and both started with ./gradlew runClient and loaded the mod with no missing-model or missing-texture warnings. The loot table, tags and recipe are read only when a world loads, which wasn’t done for this page. Their folders and formats follow Mojang’s notes, linked in each step.

File Path in src/main/resources/ Without it
Block registration Java (ModBlocks) No block
Block item registration Java (ModItems) The block has no item, so it can’t be in an inventory
Blockstate assets/guidemod/blockstates/ruby_block.json Black and magenta in the world
Block model assets/guidemod/models/block/ruby_block.json Black and magenta in the world
Item model assets/guidemod/models/item/ruby_block.json Black and magenta in the inventory
Texture assets/guidemod/textures/block/ruby_block.png Black and magenta
Loot table data/guidemod/loot_table/blocks/ruby_block.json Breaking it drops nothing
Name assets/guidemod/lang/en_us.json The name shows as block.guidemod.ruby_block
Mining tags data/minecraft/tags/block/mineable/pickaxe.json, .../needs_iron_tool.json Mines slowly and drops nothing, with requiresCorrectToolForDrops()
Recipe (optional) data/guidemod/recipe/ruby_block.json Not craftable

assets holds what a resource pack would (models, textures, names). data holds what a data pack would (loot tables, recipes, tags). The mod id is the folder name under both, and the file name is the block’s id.

Fabric 1.21.1 registers into the game’s block registry when the class loads. The mod’s main class calls ModBlocks.register() from onInitialize() so the class loads in time:

public final class ModBlocks {
public static final Block RUBY_BLOCK = register("ruby_block",
new Block(BlockBehaviour.Properties.of()
.mapColor(MapColor.COLOR_RED)
.strength(5.0F, 6.0F)
.sound(SoundType.METAL)
.requiresCorrectToolForDrops()));
private static Block register(String name, Block block) {
return Registry.register(BuiltInRegistries.BLOCK, GuideMod.id(name), block);
}
// Called from GuideMod#onInitialize; loading this class registers the blocks above.
public static void register() {
}
}

GuideMod.id(name) is ResourceLocation.fromNamespaceAndPath(MOD_ID, name), the form 1.21 uses. Older tutorials write new ResourceLocation(...) or new Identifier(...).

NeoForge 1.21.1 puts the block in a DeferredRegister, and the mod’s constructor registers it on the mod event bus with ModBlocks.BLOCKS.register(modEventBus):

public final class ModBlocks {
public static final DeferredRegister.Blocks BLOCKS = DeferredRegister.createBlocks(GuideMod.MOD_ID);
public static final DeferredBlock<Block> RUBY_BLOCK = BLOCKS.registerSimpleBlock("ruby_block",
BlockBehaviour.Properties.of()
.mapColor(MapColor.COLOR_RED)
.strength(5.0F, 6.0F)
.sound(SoundType.METAL)
.requiresCorrectToolForDrops());
}

registerSimpleBlock makes a plain Block from the properties. For your own block class, registerBlock takes a factory, such as RubyBlock::new. NeoForge’s docs warn: “Do not call new Block() outside registration!”

Property Here Effect
mapColor MapColor.COLOR_RED The block’s colour on maps
strength(hardness, resistance) 5.0F, 6.0F How long it takes to mine, and how well it resists explosions
sound SoundType.METAL Sounds when placed, broken and walked on
requiresCorrectToolForDrops() Drops only when mined with a tool from its tags (step 7)

These are Mojang’s names, which both templates and Fabric’s 1.21.1 code samples use. Fabric’s prose on the same page still says .requiresTool(), the Yarn name of requiresCorrectToolForDrops(). Code copied from a Yarn tutorial into a Mojang-names project doesn’t compile. That is a common reason a tutorial’s code fails.

Step 2: How do you register the block item?

Section titled “Step 2: How do you register the block item?”

A block and its item are separate registrations. Fabric:

public static final Item RUBY_BLOCK = register("ruby_block", new BlockItem(ModBlocks.RUBY_BLOCK, new Item.Properties()));

NeoForge:

public static final DeferredItem<BlockItem> RUBY_BLOCK = ITEMS.registerSimpleBlockItem("ruby_block", ModBlocks.RUBY_BLOCK);

Give the item the block’s id. The item model and the loot table refer to it by that id.

Step 3: How do you put it in a creative tab?

Section titled “Step 3: How do you put it in a creative tab?”

Fabric, with Fabric API’s ItemGroupEvents, called from onInitialize():

ItemGroupEvents.modifyEntriesEvent(CreativeModeTabs.BUILDING_BLOCKS).register(entries -> entries.accept(ModItems.RUBY_BLOCK));

NeoForge, with BuildCreativeModeTabContentsEvent on the mod event bus (modEventBus.addListener(ModCreativeTabs::addToVanillaTabs)):

public static void addToVanillaTabs(BuildCreativeModeTabContentsEvent event) {
if (event.getTabKey() == CreativeModeTabs.BUILDING_BLOCKS) {
event.accept(ModItems.RUBY_BLOCK);
}
}

Step 4: What goes in the blockstate and models?

Section titled “Step 4: What goes in the blockstate and models?”

The blockstate says which model to show for each state. A block with no states has one variant, "":

{
"variants": {
"": {
"model": "guidemod:block/ruby_block"
}
}
}

The block model, models/block/ruby_block.json, uses the same texture on all six sides:

{
"parent": "minecraft:block/cube_all",
"textures": {
"all": "guidemod:block/ruby_block"
}
}

The item model, models/item/ruby_block.json, reuses the block model:

{
"parent": "guidemod:block/ruby_block"
}

guidemod:block/ruby_block means assets/guidemod/models/block/ruby_block.json in a "model" or "parent", and assets/guidemod/textures/block/ruby_block.png in "textures".

A 16 × 16 PNG at assets/guidemod/textures/block/ruby_block.png, the size of vanilla block textures. A wrong path or file name shows the black and magenta “missing texture” pattern.

The loot table at data/guidemod/loot_table/blocks/ruby_block.json:

{
"type": "minecraft:block",
"pools": [
{
"rolls": 1,
"entries": [
{
"type": "minecraft:item",
"name": "guidemod:ruby_block"
}
],
"conditions": [
{
"condition": "minecraft:survives_explosion"
}
]
}
]
}

The folder is loot_table, singular. Mojang renamed loot_tables to loot_table, and recipes to recipe, in snapshot 24w21a for 1.21 (Minecraft Snapshot 24w21a). On 1.21 and newer the game doesn’t read the old folder names.

Step 7: How do you make it need a pickaxe?

Section titled “Step 7: How do you make it need a pickaxe?”

requiresCorrectToolForDrops() alone makes the block drop nothing with any tool. Tags say which tool counts. Add the block to the pickaxe tag, data/minecraft/tags/block/mineable/pickaxe.json:

{
"replace": false,
"values": [
"guidemod:ruby_block"
]
}

and to a tier tag in the same folder, such as needs_iron_tool.json (or needs_stone_tool.json, needs_diamond_tool.json), with the same content. "replace": false adds to Minecraft’s tag instead of replacing it. These files go under the minecraft namespace because the tags are Minecraft’s.

The folder is tags/block, singular. Snapshot 24w19a renamed tags/blocks to tags/block and tags/items to tags/item (Minecraft Snapshot 24w19a).

In assets/guidemod/lang/en_us.json:

{
"block.guidemod.ruby_block": "Ruby Block"
}

The key is block.<mod id>.<block id>. Items use item.<mod id>.<item id>.

A shaped recipe at data/guidemod/recipe/ruby_block.json, nine rubies to one block (the ruby item is registered like any other item):

{
"type": "minecraft:crafting_shaped",
"pattern": [
"RRR",
"RRR",
"RRR"
],
"key": {
"R": {
"item": "guidemod:ruby"
}
},
"result": {
"id": "guidemod:ruby_block"
}
}

From 1.20.5 a recipe’s result is an item stack, written with "id" (Mojang’s notes for snapshots 24w09a and 24w10a). On 1.20.4 and older it was "item", in a recipes folder.

Terminal window
./gradlew runClient

The block is in the Building Blocks tab of the creative inventory. In a world with cheats on, /give @s guidemod:ruby_block gives it. Break it with an iron pickaxe to check the loot table and tags, and with a stone pickaxe to check that it drops nothing.

What you see Look at
Black and magenta block The blockstate’s model id, the model’s texture id, the PNG’s path and name
block.guidemod.ruby_block as the name lang/en_us.json, and that it is in assets/<mod id>/lang/
No drop with the right pickaxe The loot table’s folder (loot_table) and the tag folders (tags/block)
Drops with any tool, or by hand requiresCorrectToolForDrops() missing from the properties
Game crashes at start with a registry error The block is created outside registration, or the id has capitals

Yes. Both loaders can generate models, blockstates, loot tables, tags and recipes from Java at build time: Fabric with its data generation API and ./gradlew runDatagen, NeoForge with ./gradlew runData. The output goes to src/generated/resources/. Hand-written files, as on this page, are easier to read for a first block. Generators pay off once you have many.

  • Linen Check (Free) reads registrations, models, loot tables and names the way the game will, and tells you which file to change and how.
  • The Assets board shows every block and item as a card with its texture and what it lacks.

Next: How to make a Minecraft mod for the whole path, or Set up a Fabric mod and Set up a NeoForge mod for the versions each template uses.

Checked on 3 November 2026.