Terrain Diffusion Fabric Mod

This is a Minecraft Fabric mod integrating Terrain Diffusion.

Requirements

• Minecraft with Fabric and the Fabric API Mod installed
• An NVIDIA GPU is strongly recommended. CPU inference works but is slow (see Configuration below to use the CPU).
• VRAM needed: 1.5GB

Setup Instructions (Windows + NVIDIA GPU only)

On Linux? Follow the Official ONNX Runtime instructions. The required CUDA and cuDNN versions are the same as windows.

Step 1: Install CUDA 12

Go to the CUDA Toolkit Archive and download any 12.x version.

⚠️ Do not install version 13 — it isn't supported yet.

Step 2: Install cuDNN 9

Go to the cuDNN download page and download any 9.x version.

Step 3: Add CUDA to PATH

After installing, find your CUDA bin folder containing cudart64_12.dll. It should look like this:

C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.9\bin

The version number (e.g. v12.9) may differ slightly, that's fine. Before copying the path, confirm the folder contains a file named cudart64_12.dll.

Then add this path to your system PATH. (How do I edit PATH on Windows?)

Ensure that you add this folder to the system path or PATH variable, as shown in the link above. Do not create a new variable.

Step 4: Add cuDNN to PATH

Find the cuDNN folder containing cudnn64_9.dll. It should look something like this:

C:\Program Files\NVIDIA\CUDNN\v9.x\bin\12.x\x64

9.x and 12.x should be your cuDNN and CUDA version respectively. Confirm the folder contains cudnn64_9.dll, then add it to PATH the same way.

Step 5: Restart your PC

You may need to restart your PC for PATH changes to take effect. Once you're back, you're all set.

Usage

1. Download the mod jar from Releases for your Minecraft version and place it in your Minecraft mods/ folder. Make sure the Minecraft version matches.
2. Launch Minecraft, at least once online to download the models (~2.5GB).
3. Create a world, and select the Terrain Diffusion world type. Click Customize to set the World Scale (see Per-world settings below).

Exploring the World

The mod includes a built-in terrain explorer web UI. Run the /td-explore command in-game; it will print a clickable link (e.g. http://localhost:19801) that opens an interactive map in your browser. Click the map on the left to open a "detailed view". Click the detailed view to get coordinates in the bottom left. You can also filter for certain climates.

Use the explorer to scout continents, mountains, islands, and other interesting terrain before venturing out in Minecraft.

Configuration

Edit config/terrain-diffusion-mc.properties (created automatically on first launch):

# Terrain Diffusion MC configuration

# Inference device: "cpu", "gpu", or "auto" (try GPU first then fall back to CPU).
# Defaults to "gpu" so startup fails loudly if CUDA is expected but not detected.
# Set to "cpu" explicitly if you do not have a CUDA-capable GPU.
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

Per-world settings

For Terrain Diffusion worlds, click Customize in world creation and set:

• World Scale (integer 1..6)

This value is saved with the world save and affects:

• how many real-world meters each block represents (scale=1 => 30m/block, scale=2 => 15m/block, etc.)
• world max height for newly created worlds (assumes tallest point is 10000 real-world meters)
• 2 is recommended for a good balance of scale and playability. Use 1 for smaller, more compressed worlds.

Common Issues

A dynamic link library (DLL) initialization routine failed

This can happen for some older Java versions. Please update to the most recent version of Java 21 or higher. The latest Microsoft OpenJDK 21 version is known to work.

LoadLibrary failed with error 126

This is typically due to an improper CUDA or cuDNN installation. Things to check:

• The appropriate CUDA folder is in PATH, and the folder contains cudart64_12.dll
• The appropriate cuDNN folder is in PATH, and the folder contains cudnn64_9.dll
• CUDA version is 12.x
• cuDNN version is 9.x

If your issue is still not resolved, please raise it here.

Building from Source

1. Clone this repository.
2. Build with Gradle (online connection required during build to fetch the pinned model manifest metadata):

./gradlew build

At runtime, the mod downloads required model assets from the pinned Hugging Face commit on first launch into .minecraft/terrain-diffusion-models and verifies SHA-256 checksums before use. The released jar bundles onnxruntime_gpu (CUDA). ONNX Runtime also supports other execution providers (DirectML, TensorRT, ROCm, etc.). See the ORT provider documentation if you want to build with a different backend.

Note For Mod Developers

While modifying the AI terrain itself is quite complex, the integration with Minecraft biomes is extremely simple. The model outputs elevation + 4 climate variables, and this is converted to Minecraft biomes with hand-written rules. This is the most immediate way to improve the quality of the terrain and is relatively easy, but takes time to get realistic. The entire biome classifier is only 250 lines.

The terrain diversity far outpaces the biome diversity and there's a real opportunity to close that gap. I'm hoping someone goes crazy with it.