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.
Which files does a block need?
Section titled “Which files does a block need?”| 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.
Step 1: How do you register the block?
Section titled “Step 1: How do you register the block?”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!”
What do the properties mean?
Section titled “What do the properties mean?”| 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".
Step 5: What should the texture be?
Section titled “Step 5: What should the texture be?”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.
Step 6: How do you make it drop itself?
Section titled “Step 6: How do you make it drop itself?”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).
Step 8: How do you name it?
Section titled “Step 8: How do you name it?”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>.
Step 9: How do you make it craftable?
Section titled “Step 9: How do you make it craftable?”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.
Step 10: How do you test it?
Section titled “Step 10: How do you test it?”./gradlew runClientThe 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 |
Can data generation write these files?
Section titled “Can data generation write these files?”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.
In Linen
Section titled “In Linen”- 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.
Sources
Section titled “Sources”Checked on 3 November 2026.
- Fabric: Creating Your First Block (1.21.1)
- NeoForge: Blocks (1.21.1), Items (1.21.1)
- Mojang: Minecraft Snapshot 24w19a (tag folders, 9 May 2024), Minecraft Snapshot 24w21a (loot table and recipe folders, 21 May 2024), 24w09a and 24w10a (item stack format in recipes)