NeoTerrain Diffusion

NeoTerrain Diffusion

Этот проект — порт оригинального Fabric-мода Terrain Diffusion Minecraft mod на NeoForge, который интегрирует модель генерации мира Terrain Diffusion в Minecraft.

Текущий статус

На данный момент порт поддерживает только серверное использование.

Он предназначен для выделенного сервера NeoForge. Сейчас это не полноценная клиентская замена для процесса создания мира, клиентского интерфейса или одиночной игры из Fabric-мода.

Для этого сервера настройка мира выполняется через server.properties, а не через экран создания мира в клиенте Minecraft.

Проверенный локальный сервер

Эта реализация собрана и проверена для:

• Minecraft 1.21.1
• NeoForge 21.1.233
• Java 21
• Windows 10/11
• Инференс на GPU через DirectML
• Среда выделенного сервера

Проверенный jar:

terrain-diffusion-mc-neoforge-2.2.0-neoforge.1-windows+1.21.1.jar

Локальный сервер, использующий этот мод:

C:\Users\Collin\Desktop\Server 1.21.1

Требования

• Выделенный сервер NeoForge 1.21.1
• NeoForge 21.1.233 или новее в той же ветке 21.1.x
• Java 21
• Windows с GPU, совместимым с DirectML, для проверенной сборки
• Минимум около 1,5 ГБ свободной видеопамяти
• Около 2,5 ГБ дополнительной системной памяти для загрузки модели
• Доступ в интернет при первом запуске, чтобы скачались файлы модели

Проверенный лаунчер локального сервера использует эту среду Java 21:

C:\Users\Collin\AppData\Roaming\ModrinthApp\meta\java_versions\zulu21.48.17-ca-jre21.0.10-win_x64\bin\java.exe

Поведение GPU

Сборка для Windows использует DirectML для инференса на GPU.

При корректном запуске в логе должно быть:

Terrain diffusion inference: DirectML
ONNX model 'coarse' loaded on GPU
ONNX model 'base' loaded on GPU
ONNX model 'decoder' loaded on GPU

Сборка этого порта для Windows ориентирована в первую очередь на DirectML и не должна предупреждать об отсутствии CUDA при обычном запуске. CUDA для этой серверной сборки под Windows не требуется.

Установка на сервер

Поместите NeoForge jar в папку mods выделенного сервера.

Для этого локального сервера jar хранится в папке mods привязанного профиля Modrinth, чтобы шаг синхронизации сервера мог скопировать его в:

C:\Users\Collin\Desktop\Server 1.21.1\server-runtime\mods

Скрипт синхронизации также исключает известные клиентские и рендер-моды из серверной среды с помощью:

C:\Users\Collin\Desktop\Server 1.21.1\server-mod-exclusions.txt

Локальный сервер

Запустите:

C:\Users\Collin\Desktop\Server 1.21.1\Start-Server.bat

Этот лаунчер:

1. Синхронизирует совместимые с сервером моды из профиля Modrinth.
2. Не допускает исключённые клиентские и рендер- jar в server-runtime\mods.
3. Запускает выделенный сервер NeoForge с Java 21.

Создание мира Terrain Diffusion на сервере

Поскольку сейчас это серверный порт, настраивайте мир в server.properties.

Текущая конфигурация локального сервера:

level-name=terrain-diffusion-world
level-type=terrain-diffusion-mc\:terrain_diffusion

Активный файл:

C:\Users\Collin\Desktop\Server 1.21.1\server-runtime\server.properties

При первом запуске мод скачивает и подготавливает файлы модели в:

C:\Users\Collin\Desktop\Server 1.21.1\server-runtime\terrain-diffusion-models

Конфигурация

Серверный конфиг создаётся в:

config\terrain-diffusion-mc.properties

Для этого локального сервера полный путь:

C:\Users\Collin\Desktop\Server 1.21.1\server-runtime\config\terrain-diffusion-mc.properties

Текущие настроенные значения:

# Inference device: "cpu", "gpu", or "auto".
# On the Windows build, "gpu" means DirectML.
inference.device=gpu

# Keep all three models loaded on GPU instead of recreating DirectML sessions
# between pipeline stages. This is faster when enough VRAM is available.
inference.offload_models=false

# Validate SHA-256 for model files already on disk.
validate_model=true

# Local web UI port for /td-explore.
explorer.port=19801

# Terrain generation region side length in blocks. Must be a power of 2.
tile_size=256

# Spawn land-search coarse-pixel region sizes.
spawn_search.initial_size=16
spawn_search.max_size=128

Если памяти GPU становится мало, задайте:

```properties
inference.offload_models=true

Это снижает пиковое потребление VRAM, но может замедлить генерацию.

Terrain Explorer

Порт включает серверную команду исследования terrain:

/td-explore

Запустите её в игре. Сервер выведет ссылку на локальный веб-интерфейс, обычно:

http://localhost:19801

Используйте исследователь, чтобы разведать континенты, горы, острова, климаты и полезные координаты перед путешествием в игре.

Масштаб мира

Серверный порт поддерживает значения масштаба мира 1..6.

Масштаб по умолчанию — 2.

Для миров на выделенном сервере выбранный масштаб хранится в сохранении мира:

terrain-diffusion-world\data\terrain_diffusion_world_settings.dat

Поведение масштаба:

• scale=1 более сжатый и запускает Terrain Diffusion чаще.
• scale=2 — баланс по умолчанию для играбельности и производительности.
• Более высокие значения масштаба покрывают больше блоков на каждый сгенерированный образец terrain и переносят больше работы на генерацию мира Minecraft на стороне CPU.

Поскольку этот порт сейчас только серверный, в такой конфигурации нет поддерживаемого клиентского экрана Customize при создании мира для изменения масштаба. Считайте масштаб частью сохранения серверного мира.

Частые проблемы

CUDA not available

Эта сборка Windows DirectML не должна выдавать такое предупреждение. Если оно появляется, сервер, вероятно, запускает старый jar или неверный вариант сборки. Переустановите jar Windows DirectML и повторите синхронизацию модов сервера.

DirectML not available

Обновите драйвер GPU и убедитесь, что машина имеет GPU, совместимый с DirectML. Чтобы запустить без ускорения GPU для диагностики, задайте:

inference.device=cpu

Вывод на CPU намного медленнее и не рекомендуется для обычного использования на сервере.

A dynamic link library (DLL) initialization routine failed

Используйте актуальную среду выполнения Java 21. Проверенный локальный сервер использует среду выполнения Zulu Java 21 от Modrinth через Start-Server.bat.

java.lang.IllegalStateException: Failed to load terrain-diffusion models

Обычно это означает одно из следующего:

• Загрузка модели не удалась.
• Файл модели не прошёл проверку.
• Серверу не хватило RAM или VRAM во время загрузки модели.

Проверьте последний лог сервера и файлы в:

server-runtime\terrain-diffusion-models

Сервер запускает обычный мир

Проверьте server.properties и убедитесь, что указано:

level-type=terrain-diffusion-mc\:terrain_diffusion

Также убедитесь, что jar Terrain Diffusion присутствует в server-runtime\mods.

Сборка этого порта

Используйте JDK Java 21 для Gradle.

На этой машине сработал этот JDK:

C:\Program Files\Android\openjdk\jdk-21.0.8

Соберите jar Windows DirectML:

$env:JAVA_HOME='C:\Program Files\Android\openjdk\jdk-21.0.8'
$env:Path="$env:JAVA_HOME\bin;$env:Path"
.\gradlew.bat build -PuseDml=true

Собранный jar записывается в:

build\libs\terrain-diffusion-mc-neoforge-2.2.0-neoforge.1-windows+1.21.1.jar

Для локального сервера скопируйте пересобранный jar в оба места:

C:\Users\Collin\Desktop\Server 1.21.1\mods
C:\Users\Collin\Desktop\Server 1.21.1\server-runtime\mods

Затем проверьте:

powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Users\Collin\Desktop\Server 1.21.1\Sync-ServerMods.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Users\Collin\Desktop\Server 1.21.1\Validate-ServerBoot.ps1" -TimeoutSeconds 900

Ожидаемый результат:

Result: done
Terrain diffusion inference: DirectML

Поиск точки спавна: размеры грубопиксельных регионов для поиска наземного спавна рядом с (0, 0). Начинается с initial_size x initial_size и расширяется на 8 на каждом шаге вплоть до max_size x max_size. Каждый грубый пиксель покрывает большую область (сотни блоков), так что 16–128 обычно достаточно. spawn_search.initial_size=16 spawn_search.max_size=128

### Настройки для каждого мира

Для миров Terrain Diffusion нажмите **Customize** при создании мира и задайте:

- `World Scale` (целое `1..6`)

Это значение сохраняется вместе с сохранением мира и влияет на:

- сколько реальных метров представляет каждый блок (`scale=1` => `30m/block`, `scale=2` => `15m/block` и т. д.)
- максимальную высоту мира для новых создаваемых миров (предполагается, что высшая точка — 10000 реальных метров)
- 2 рекомендуется для хорошего баланса масштаба и играбельности. Используйте 1 для меньших, более сжатых миров.
- Низкие значения сильнее нагружают GPU (Terrain Diffusion запускается чаще), а высокие сильнее нагружают CPU (большая высота мира). Большинство современных GPU упрутся в CPU примерно на масштабе 2 или 3.

## Частые проблемы

**A dynamic link library (DLL) initialization routine failed**

Это может случаться на некоторых старых версиях Java. Пожалуйста, обновитесь до самой свежей версии Java 21 или выше. [Последняя версия Microsoft OpenJDK 21](https://learn.microsoft.com/en-us/java/openjdk/download) известна как рабочая.

**LoadLibrary failed with error 126** *(только для сборки CUDA)*

Обычно это связано с неправильной установкой CUDA или cuDNN. Смотрите [CUDA_INSTALL.md](CUDA_INSTALL.md) для шагов по устранению.

**java.lang.IllegalStateException: Failed to load terrain-diffusion models**

Обычно это указывает на ошибку "out of memory" (в логах это тоже должно быть видно).
Модели Terrain Diffusion занимают около 2.5GB RAM, так что убедитесь, что выделили достаточно RAM с учётом этого.

**Если ваша проблема всё ещё не решена, пожалуйста, [сообщите о ней здесь](https://github.com/xandergos/terrain-diffusion-mc/issues/new).**

## Сборка из исходников

Во время сборки требуется подключение к интернету для получения закреплённых метаданных манифеста моделей с Hugging Face.

Сборка `-windows` требует `libs/onnxruntime-dml.jar`, который предоставляется как часть репозитория. Смотрите [Building onnxruntime with DirectML](#building-onnxruntime-with-directml) для сборки из исходников. 

Сборка для Windows (DirectML):

./gradlew build -PuseDml=true

Сборка для CUDA:

./gradlew build -PuseCuda=true

Сборка для CPU (также автоматически обрабатывает macOS/CoreML):

./gradlew build -PuseCpu=true

Собрать всё:

./gradlew buildAll

Сборка onnxruntime с DirectML

Требования

• Windows 10 SDK (10.0.17134.0) — для Windows 10 версии 1803 или новее
• Инструментарий Visual Studio 2017 — установите Desktop development with C++ через установщик VS
• Инструментарий Visual Studio 2022 — то же самое
• Python 3.10+: https://python.org/
• CMake 3.28 или выше

Держите оба инструментария VS в актуальном состоянии. Полности — в документации по сборке ONNX Runtime и требованиях к DirectML EP.

Шаги

Выполняйте все команды из Developer Command Prompt for VS 2022.

git clone --recursive https://github.com/Microsoft/onnxruntime.git
cd onnxruntime
.\build.bat --config RelWithDebInfo --build_shared_lib --parallel --compile_no_warning_as_error --skip_submodule_sync --use_dml --build_java --build

Собранный jar появится в java/build/. Переименуйте его в onnxruntime-dml.jar и положите в libs/ в этом репозитории.

Заметка для разработчиков модов

Хотя изменять сам AI-рельеф довольно сложно, интеграция с биомами Minecraft предельно проста. Модель выдаёт высоту + 4 климатические переменные, и это преобразуется в биомы Minecraft с помощью написанных вручную правил. Это самый прямой способ улучшить качество рельефа, и он относительно прост, но требует времени, чтобы добиться реалистичности. Весь классификатор биомов — всего 250 строк.

Разнообразие рельефа сильно опережает разнообразие биомов, и есть реальная возможность сократить этот разрыв. Надеюсь, кто-нибудь возьмётся за это как следует. explorer.port=19801

Поиск спавна: размеры областей грубых пикселей для поиска наземного спавна рядом с (0, 0).

Начинается с initial_size x initial_size и расширяется на 8 на каждом шаге вплоть до max_size x max_size.

Каждый грубый пиксель покрывает большую область (сотни блоков), так что 16–128 обычно достаточно.

spawn_search.initial_size=16 spawn_search.max_size=128

### Настройки для каждого мира

Для миров Terrain Diffusion нажмите **Customize** при создании мира и задайте:

- `World Scale` (целое число `1..6`)

Это значение сохраняется вместе с миром и влияет на:

- сколько реальных метров представляет каждый блок (`scale=1` => `30м/блок`, `scale=2` => `15м/блок` и т. д.)
- максимальную высоту мира для новых миров (предполагается, что самая высокая точка — 10000 реальных метров)
- для хорошего баланса масштаба и играбельности рекомендуется 2. Используйте 1 для меньших, более сжатых миров.
- Меньшие значения сильнее нагружают GPU (Terrain Diffusion запускается чаще), а большие — сильнее нагружают CPU (больше высота мира). Большинство современных GPU упрутся в CPU примерно на scale 2 или 3.

## Частые проблемы

**Сбой инициализации динамической библиотеки (DLL)**

Такое может случаться на некоторых старых версиях Java. Обновитесь до самой свежей версии Java 21 или выше. [Последняя Microsoft OpenJDK 21](https://learn.microsoft.com/en-us/java/openjdk/download) точно работает.

**LoadLibrary failed with error 126** *(только для сборки с CUDA)*

Обычно это связано с неправильной установкой CUDA или cuDNN. Шаги по устранению — в [CUDA_INSTALL.md](CUDA_INSTALL.md).

**java.lang.IllegalStateException: Failed to load terrain-diffusion models**

Обычно это означает ошибку «не хватает памяти» (в логах это тоже должно быть видно).
Модели Terrain Diffusion занимают около 2.5 ГБ оперативной памяти, так что выделите достаточно RAM с учётом этого.

**Если ваша проблема всё ещё не решена, пожалуйста, [сообщите о ней здесь](https://github.com/xandergos/terrain-diffusion-mc/issues/new).**

## Сборка из исходников

Во время сборки требуется подключение к интернету, чтобы получить закреплённые метаданные манифеста модели с Hugging Face.

Сборка `-windows` требует `libs/onnxruntime-dml.jar`, который поставляется вместе с репозиторием. Смотрите [Сборка onnxruntime с DirectML](#building-onnxruntime-with-directml), чтобы собрать из исходников.

Сборка для Windows (DirectML):

./gradlew build -PuseDml=true

Сборка для CUDA:

./gradlew build -PuseCuda=true

Сборка для CPU (также автоматически обрабатывает macOS/CoreML):

./gradlew build -PuseCpu=true

Собрать всё:

./gradlew buildAll

### Сборка onnxruntime с DirectML

**Требования**

- [Windows 10 SDK (10.0.17134.0)](https://developer.microsoft.com/en-us/windows/downloads/sdk-archive/index-legacy) — для Windows 10 версии 1803 или новее
- Инструментарий Visual Studio 2017 — установите *Desktop development with C++* из установщика VS
- Инструментарий Visual Studio 2022 — то же самое
- Python 3.10+: [https://python.org/](https://python.org/)
- CMake 3.28 или выше

Держите оба инструментария VS в актуальном состоянии. Подробности в [документации по сборке ONNX Runtime](https://onnxruntime.ai/docs/build/inferencing.html) и [требованиях к DirectML EP](https://onnxruntime.ai/docs/execution-providers/DirectML-ExecutionProvider.html#build).

**Шаги**

Выполняйте все команды из **Developer Command Prompt for VS 2022**.

git clone --recursive https://github.com/Microsoft/onnxruntime.git cd onnxruntime .\build.bat --config RelWithDebInfo --build_shared_lib --parallel --compile_no_warning_as_error --skip_submodule_sync --use_dml --build_java --build

Собранный jar появится в `java/build/`. Переименуйте его в `onnxruntime-dml.jar` и поместите в `libs/` в этом репозитории.

## Заметка для разработчиков модов

Хотя изменение самого ИИ-ландшафта довольно сложное, интеграция с биомами Minecraft чрезвычайно проста. Модель выдаёт высоту + 4 климатические переменные, и это преобразуется в биомы Minecraft с помощью написанных вручную правил. Это самый прямой способ улучшить качество ландшафта, и он относительно прост, но требует времени, чтобы получить реалистичный результат. Весь классификатор биомов — [всего 250 строк](https://github.com/xandergos/terrain-diffusion-mc/blob/master/src/main/java/com/github/xandergos/terraindiffusionmc/pipeline/BiomeClassifier.java).

Разнообразие ландшафта намного опережает разнообразие биомов, и есть реальная возможность сократить этот разрыв. Надеюсь, кто-нибудь сойдёт с ума по этому поводу.