terrain-diffusion-mc generates Minecraft terrain with a diffusion model

A diffusion model drives the world type, not a noise generator

terrain-diffusion-mc is a Minecraft Fabric mod that generates terrain with a diffusion model instead of a conventional noise generator. It is a wrapper around the separate terrain-diffusion project by the same author, and the mod exposes that model to players as a world type called Terrain Diffusion in the world creation screen. The point is not extra blocks or a biome overlay. The surface, the continent shapes, the mountain ranges and the coastlines are sampled from a learned model as one coherent sample, so a shoreline and the ridge behind it tend to agree with each other instead of being layered on top of each other. The README states that the research behind the mod was accepted to SIGGRAPH 2026, which means the generation method went through peer review rather than shipping as an untested experiment. The audience is players and mod pack authors who want a world layout that does not look procedurally repetitive, and who are willing to spend VRAM, RAM and a one time 2.5GB download on it. The primary language of the repository is Java, and the licence is MIT.

Windows, CUDA and CPU builds trade setup work for speed

Three builds ship on the Releases page and the choice is about hardware, not features. The Windows build is described as the recommended one. It works on Windows with any modern GPU, it uses DirectML, and no setup is required. The CUDA build targets NVIDIA GPUs and needs a CUDA plus cuDNN install before it will run, so it adds a real setup step. The CPU build supports everything else and needs nothing, but the project says plainly that it is slow unless you are on macOS, because the CPU build automatically uses CoreML for hardware acceleration on Apple Silicon. The CUDA build is only worth taking if you are on Linux, or you have an NVIDIA GPU and prefer CUDA, and even there it may improve performance. Resource requirements are listed as 1.5GB of VRAM and 2.5GB of RAM, with the note that the RAM figure may need to be added to Minecraft's own allocation.

The first launch pulls 2.5GB of models before any world exists

Installation is a jar drop followed by a large first download. Pick the build that matches your machine, download the mod jar for your Minecraft version from the Releases page, and place it in the Minecraft mods folder. The Minecraft version has to match, and the game also needs Fabric plus the Fabric API mod installed. On the first launch you must be online at least once, because roughly 2.5GB of models are downloaded into a directory under .minecraft. Once that is in place you create a world and select the Terrain Diffusion world type, then click Customize to set the World Scale before generation begins. The mod then searches for a land spawn point near the world origin on its own. If the area around (0, 0) is entirely ocean, that search takes a while, and the project points you at the /td-explore command to scout further out rather than sitting in a loading screen.

The /td-explore browser map scouts terrain before you spawn

The terrain explorer is a web UI served from the machine the game runs on, and it is the tool for choosing a destination before you spawn. Running /td-explore in game prints a clickable link, for example http://localhost:19801, which opens an interactive map in the browser. Clicking the map on the left opens a detailed view, and clicking inside that detailed view reports coordinates in the bottom left corner, which is how you pick the point you want to travel to. The map can also be filtered for certain climates. The intended workflow is to survey continents, mountains and islands from the browser and then make the trip in game, instead of flying blind across an unfamiliar seed. The port is not hard coded: explorer.port in the configuration file sets it, and the shipped value in the example file is 19801. Because the UI is served on localhost, it is not something you can share with a friend over the network without extra work.

World Scale 1 to 6 moves the bottleneck between GPU and CPU

World Scale is the one per-world knob, an integer from 1 to 6 that is saved with the world save, and it changes what a block means. At scale 1 each block represents 30 real world meters, at scale 2 each block is 15 meters, and the value also determines the maximum world height for newly created worlds, on the assumption that the tallest point is 10000 real world meters. The project recommends 2 as a balance between scale and playability, and suggests 1 for smaller, more compressed worlds. The tradeoff is not only about looks. Lower values put more stress on the GPU, because Terrain Diffusion runs more often, while higher values put more stress on the CPU through the larger world height. The README says most modern GPUs will be bottlenecked by the CPU around scale 2 or 3, so pushing the scale past that point buys bigger terrain at the cost of chunk generation time. The value is set in the Customize screen at world creation, and it is stored per world rather than globally.

inference.device decides between a loud failure and a silent fallback

The configuration file is created automatically on first launch as config/terrain-diffusion-mc.properties, and the most consequential line in it is inference.device. The key accepts cpu, gpu or auto, where auto tries the GPU first and then falls back to the CPU. GPU builds default to gpu specifically so that startup fails loudly if no GPU is detected, which is a deliberate choice against a silent drop to slow generation, while the CPU build defaults to auto so it can use CoreML on macOS. The shipped values also enable offloading of inactive models between pipeline stages, which keeps peak VRAM to about 1.5 to 2 GB, and turn on SHA-256 validation for pre-existing files in .minecraft/terrain-diffusion-models. Setting validate_model to false is the documented way to supply your own models or config files without hash checks.

# Terrain Diffusion MC configuration

# Inference device: "cpu", "gpu", or "auto" (try GPU first then fall back to CPU).
# "gpu" uses DirectML on the -windows build, or CUDA on the -cuda build.
# GPU builds default to "gpu" so startup fails loudly if no GPU is detected.
# CPU build defaults to "auto": uses CoreML on macOS, otherwise CPU.
inference.device=gpu

# Offload inactive models from VRAM between pipeline stages.
# Keeps peak VRAM to ~1.5-2 GB. Set to false if you have ~2.5+ GB free for slightly
# faster generation.
inference.offload_models=true

# Validate SHA-256 for pre-existing files in .minecraft/terrain-diffusion-models.
# Set to false if you want to provide custom models/config files without hash checks.
validate_model=true

# Port for the local terrain explorer web UI (/td-explore).
explorer.port=19801

# Spawn search: coarse-pixel region sizes for finding a land spawn near (0, 0).
# Starts at initial_size x initial_size and expands by 8 each step up to max_size x max_size.
spawn_search.initial_size=16
spawn_search.max_size=128

Source builds need DirectML toolchains and a pinned model manifest

Building from source has a different cost profile than installing a jar. An internet connection is required during the build, because the pinned model manifest metadata is fetched from Hugging Face, so a fully offline build is not covered. The Windows build needs libs/onnxruntime-dml.jar, which the repository already provides, and the project also documents how to build onnxruntime with DirectML yourself. That path requires the Windows 10 SDK (10.0.17134.0) for Windows 10 version 1803 or newer, both the Visual Studio 2017 and the Visual Studio 2022 toolchains with the Desktop development with C++ workload installed, Python 3.10 or newer, and CMake 3.28 or higher. The build itself is a Gradle task selected by a property per backend, with a combined target that produces all three variants.

./gradlew build -PuseDml=true
./gradlew build -PuseCuda=true
./gradlew build -PuseCpu=true
./gradlew buildAll

Out of memory, DLL 126 and Java 21 cover most reported failures

Most of the friction in this project appears as a startup error rather than as a world that looks wrong, and the README groups the recurring ones. A dynamic link library (DLL) initialization routine failed points at an old Java runtime, and the fix is to update to the most recent version of Java 21 or higher, with the latest Microsoft OpenJDK 21 stated to work. LoadLibrary failed with error 126 is scoped to the CUDA build and is typically caused by an improper CUDA or cuDNN installation, with CUDA_INSTALL.md holding the troubleshooting steps. java.lang.IllegalStateException: Failed to load terrain-diffusion models is described as an out of memory symptom, since the models take about 2.5GB of RAM, and the logs are said to show it as well. On the timeline, the last push was on 2026-05-21, and the tags around it are v2.3.0-preview for multiloader support on 2026-05-13, v2.2.0 for improved compatibility and spawning on land on 2026-05-09, and v2.1.0 for DirectML on AMD and Minecraft 1.21.1 support on 2026-04-24. The newest tag is still a preview, so the multiloader work is the part to treat as unsettled. Nothing in the project documents a rollback path or a migration note for older world saves.

Editorial conclusion

terrain-diffusion-mc suits players on Windows with a modern GPU who want a continent layout that no noise function would produce, and suits mod pack authors who can accept a one time 2.5GB download and a 1.5GB VRAM floor. It is the wrong tool for a low spec machine, for a Linux user without an NVIDIA card who does not want to install CUDA and cuDNN, and for anyone who needs a lightweight world generator. Before generating anything, check that the Minecraft version matches the jar you downloaded, that inference.device in config/terrain-diffusion-mc.properties matches the build you installed, and that the machine has room for the 2.5GB model set. The last push was on 2026-05-21, and the newest tag v2.3.0-preview is a preview.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. xandergos/terrain-diffusion-mc on GitHub