Custom Structure Modding: Complete Guide to StructureTutorialMod

If you've ever wanted to add custom structures to a Minecraft world but got overwhelmed by NBT files, template pools, and configuration, StructureTutorialMod exists specifically to untangle that mess. This teaching-focused mod breaks down the entire structure generation pipeline into four real-world examples you can read, learn from, and adapt to your own ideas. It's not a plugin or a shortcut - it's learning material disguised as code.

What This Project Does

StructureTutorialMod is a heavily commented Java mod that shows you step-by-step how to register and generate Jigsaw structures in NeoForge, Forge, and Fabric. Each branch targets a different modloader, so you can switch between them depending on what you're developing for. The creator walked through the entire structure registration process and included inline comments explaining *why* each piece matters, not just *what* it does.

The goal isn't to use this mod in your world for new features. It's to read it, understand it, and then build your own structure system. Every JSON file, every NBT placement, every processor list serves as an example. Some structures use only JSON (no code at all), while others layer in Java for advanced behavior. This range means you can start simple and work your way up.

The Four Example Structures You'll Study

The mod ships with four distinct structures, each teaching a different lesson. Think of them as difficulty levels.

JSON Only House is the beginner's starting point. It demonstrates that you don't need a single line of Java code to get a structure generating. Two NBT pieces are connected using Jigsaw blocks and a template pool. The structure even includes a chest with a loot table that generates random items when you open it for the first time. It's simple enough to understand completely in an afternoon, yet complex enough to show how pieces fit together.

Sky Fan takes the next step by adding Java code for placement logic. It refuses to spawn above terrain higher than y = 150, keeping the structure floating cleanly in the sky. This teaches you how to validate spawn locations and reject placements that don't meet your criteria. It also introduces processor lists - a way to randomize blocks throughout the structure without manually editing every variant.

Sea Boat shows how to handle biome targeting with more precision. Instead of a single biome tag, it uses two: one to specify where it *can* spawn and another to specify where it *can't*, even if the first condition is met. But it also validates that the spawn location has water, so it doesn't awkwardly place a boat on land. This is what real-world structure selection looks like.

End Phantom Balloon is the advanced example. So it uses custom placement logic to ensure it only spawns above large End islands, far from the world center. If you want structures with unusual placement rules, this is where you'll find answers.

Getting Started: Installation and Setup

Grab the latest source from GitHub and choose your branch. The main branch is NeoForge; other branches cover Fabric and Forge. You'll need JDK 21+ and Gradle installed on your system.

git clone https://github.com/TelepathicGrunt/StructureTutorialMod.git
cd StructureTutorialMod
git checkout fabric # or forge, or stay on main for neoforge./gradlew build

Once built, the JAR goes into your mods folder. When you load the mod in Minecraft 26.1.2 (or whatever your branch supports - check the commit history for older versions), the example structures start generating in most biomes. Load up a new world and fly around. You'll see houses, floating structures, boats in oceans, and balloons in the End dimension.

The real work begins when you open the `src/main/resources/data/structuretutorial/worldgen` folder. Every JSON file has explanatory comments. Open `structure/json_only_house.json` and read it line-by-line. Then cross-reference `worldgen/template_pool/json_only_house` to see how pieces connect. This hands-on reading is how you learn.

Core Concepts You'll Master

Jigsaw structures are the foundation. They're a system where you build structure pieces separately as NBT files, then connect them using Jigsaw blocks. One piece's Jigsaw block attaches to another piece's Jigsaw block, and they snap together. This modular approach means you can create complex structures by combining simple pieces. The tutorial mod uses two-piece structures, but you can nest dozens.

Template pools are the JSON files that define which pieces can connect to each other and how often each appears. A pool might say "this Jigsaw connector can attach to either Piece A (50% chance) or Piece B (50% chance)." Minecraft randomly selects from the pool each time it generates a structure, creating variation without duplicating NBT files.

Processor lists let you randomize blocks without creating multiple NBT files. Say you want some blocks in your structure to be oak wood 70% of the time and birch wood 30% of the time. Instead of building two separate NBT files, you define a processor that swaps blocks during placement. The example structures use this heavily.

Custom structure placement is where Java code enters. The vanilla system spawns structures based on biomes and spacing, but you might want custom rules. This tutorial mod shows how to override placement to add height checks, water validation, or distance-from-world-center rules. This is pure logic - no NBT involved.

Where to Find Tools and Resources

To actually *build* your own structures in survival mode, use structure blocks (that's a vanilla Minecraft feature). There's a solid video tutorial on YouTube showing how to carve out a structure, save it to NBT using structure blocks, and export it. Once you've your NBT file, you can reference it in StructureTutorialMod's template pool system.

If you need to search for specific blocks when designing your structure, minecraft.how's Block Search tool is invaluable for finding block IDs and properties. And if your structure involves the Nether, the Nether Portal Calculator helps you plan exact placements across dimensions.

For reference material on vanilla structures, all of Minecraft's worldgen JSON and NBT files are archived at mcmeta's GitHub repository. Browse those files to see how Mojang structures are built. It's a goldmine if you're stuck.

Common Stumbling Blocks (and How to Avoid Them)

Most people try to understand everything at once. Don't. Start with JSON Only House. Read every line. Build that structure from scratch using the mod as a reference. Only then move to Sky Fan. Rushing through all four examples at once guarantees confusion.

Another mistake: not understanding the difference between a structure and a structure set. A structure is the actual building you're placing. A structure set is the collection of structures Minecraft considers for placement in a biome, along with the spacing and separation rules. Both JSON files are necessary.

NBT file issues trip people up constantly. If your NBT doesn't generate, check that the file path in your template pool JSON exactly matches the actual file location (including namespace). A typo like `structuretutorial:house` when you meant `structuretutorial:json_only_house` will silently fail to generate.

One more: forgetting that you need to reload the world after modifying JSON files. Minecraft caches worldgen data. Use `/reload` in commands, or restart the server. Otherwise you'll spend an hour debugging a JSON syntax error that you already fixed ten minutes ago.

Next Steps After You've Learned

Once you understand the tutorial structures, branch out. Create your own NBT files using structure blocks in vanilla Minecraft. Add them to the template pools. Make a processor list to randomize materials. Test it in a new world.

If you're building a real mod, you'll likely want more complex placement rules. Dig into the Java code for custom structure placements. The tutorial mod's examples are readable enough to adapt.

And if you're stuck, the Minecraft modding community on Discord or specialized forums exists exactly for this. The tutorial mod's GitHub also has issues - don't hesitate to ask questions there.