PromptCraft

Программная система процедурной генерации трёхмерных воксельных структур по описанию на естественном языке. Построена на сочетании большой языковой модели с механизмом дополненной генерации (Retrieval-Augmented Generation).

Слева — исходное состояние участка мира, справа — состояние после выполнения текстового запроса.

Назначение

Модификация воксельного мира традиционно требует либо ручного размещения блоков, либо владения предметно-ориентированным синтаксисом команд. Настоящая система снимает это ограничение: неформальное описание на русском или английском языке преобразуется в детерминированную последовательность операций, применяемых непосредственно к region-файлам формата .mca.

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

Принцип работы

flowchart LR
    A["Текстовый запрос<br/>RU / EN"] --> B["Семантический поиск<br/>блоки · структуры"]
    B --> C["Языковая модель<br/>Ollama · DeepSeek"]
    C --> D["Структурированная<br/>команда (JSON)"]
    D --> E{"Валидация<br/>схема · лимиты · блоки"}
    E -- "отклонено" --> C
    E -- "принято" --> F["Исполняющее ядро"]
    F --> G[("region-файлы .mca")]
    F --> H["файл .schem"]

Loading

Запрос предварительно дополняется результатами семантического поиска: по каталогу блоков (около 800 наименований) и по корпусу готовых структур. Поиск по корпусу использует многоязычную модель векторного представления, поскольку набор данных двуязычен, а запросы формулируются преимущественно на русском языке.

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

Поддерживаемые операции

Операция	Описание
replace_blocks	Замена блоков во всём мире либо в заданном диапазоне высот посредством изменения палитры секций
fill	Заполнение области заданной формы (параллелепипед, сфера, цилиндр) одним типом блока
place_structure	Построение параметрической структуры: дом, башня, стена, пирамида, купол
place_dataset	Подбор готовой структуры из корпуса по текстовому описанию и её размещение

Установка и запуск

git clone https://github.com/Sotka229/PromptCraft.git
cd PromptCraft
python -m venv .venv && . .venv/Scripts/activate   # Linux, macOS: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Для работы с локальной моделью требуется запущенный сервер Ollama:

ollama serve
ollama pull llama3.1:8b

Запуск веб-интерфейса (по умолчанию http://127.0.0.1:7860):

python main.py

Режим командной строки:

python main.py --cli            # интерактивный режим
python main.py --list-worlds    # перечень доступных миров
python main.py --check-ollama   # проверка соединения с Ollama
python main.py -e command.json  # выполнение подготовленной команды

Перед первым запуском рекомендуется создать резервную копию мира: система записывает изменения в region-файлы непосредственно. Резервная копия с расширением .bak формируется автоматически.

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

Параметры задаются переменными окружения (файл .env, образец — .env.example): расположение каталога миров, адрес и наименование локальной модели, параметры доступа к облачному провайдеру, пути к корпусу структур и модель векторного представления.

Структура проекта

Каталог	Содержание
engine/	Чтение и запись region-файлов, кодирование упакованных состояний блоков, операции над палитрой секций, процедурная геометрия, экспорт в формат .schem, координатные преобразования
knowledge/	Векторный каталог блоков, поиск по корпусу структур, загрузка структур в формате NBT
llm/	Провайдеры языковых моделей, системная подсказка, оркестрация генерации с повторными попытками
validator/	Схемы операций и трёхуровневая проверка команд
ui/	Веб-интерфейс
tests/	Модульные и интеграционные тесты

Тестирование

pytest -q

Интеграционный тест по корпусу структур пропускается автоматически, если соответствующие переменные окружения не заданы.

Программное окружение

Python 3.11; nbtlib, Pydantic, ChromaDB, sentence-transformers, Gradio, httpx; языковые модели — Ollama (локально) либо DeepSeek (облачный провайдер).

Ограничения реализации

• Свойства блоков (ориентация лестниц, дверей и подобных элементов) при загрузке структур в формате NBT не сохраняются.
• Освещение не пересчитывается: значения SkyLight устанавливаются максимальными, пересчёт выполняется игровым движком при загрузке чанка.
• Совместимость проверена для формата данных версии 1.21 (DataVersion не ниже 2825).

Состав репозитория

В репозиторий не включены: сторонние наборы данных (корпус структур и схематики сторонних авторов), векторные индексы и кэши, формируемые автоматически при первом запуске, а также файл .env с локальными параметрами.

Каталог блоков загружается при первом запуске из репозитория PrismarineJS/minecraft-data (лицензия MIT).