Форматы обмена, CLI и MCP World Forge
Обмен форматами, CLI и внешний MCP
В переносимой папке World Forge есть CLI и MCP-исполняемые файлы; для обычного строительства они не нужны. Руководство для 0.1.0-preview.1 указывает Windows и Project Zomboid B42.20.4.
Импорт внешних форматов
| Команда | Что импортирует | Ограничения |
|---|---|---|
| Lib → Import TBX… | Однонаправленный XML prefab как штамп | Это не полный обмен проектом |
| Lib → Import LDtk… | Поддерживаемые IntGrid/entities преобразуются в комнаты, зоны и именованные плитки | Импортируется только поддерживаемое подмножество |
| Lib → Import TMX… | Поддерживаемые CSV-слои и объекты | Неподдерживаемые auto-layers и image tilesets пропускаются; это не PZ packs |
Форматы TBX, LDtk и TMX реализованы как ограниченные подмножества; полноценный round trip проекта не поддерживается.
Подключение клиента MCP
Настройте совместимый с MCP клиент так, чтобы он запускал распакованный исполняемый файл. Замените пример абсолютным путём к вашей копии; формат настроек отличается у разных клиентов.
{
"mcpServers": {
"world-forge": {
"command": "C:\\Tools\\WorldForge\\WorldForge.Mcp.exe"
}
}
}
Начните с wf_help для рецептов и wf_workflow для последовательности: задайте каталог игры, подготовьте игровые наборы, откройте проект, найдите место, осмотрите, разместите prefabs, проверьте и сохраните. Параметры см. в docs/MCP_TOOL_MAP.md.
Внешний MCP использует отдельную сессию и не разделяет камеру desktop-приложения или сессию карты. Не открывайте одну базу одновременно в обоих клиентах; сначала закройте проект в одном, затем откройте в другом. Чтобы попросить «осмотри это здание на экране», используйте встроенный Assistant.
Чтобы посмотреть команды CLI, запустите worldforge.exe --help из распакованного каталога. Экспорт подчиняется политике рабочего каталога World Forge. MCP export по умолчанию выполняет dry run; реальная запись требует dryRun: false.
Сохранение и восстановление
После важных изменений используйте File → Save или Ctrl+S. Save As создаёт отдельный снимок; Open Project продолжает сохранённый проект. Ячейки, которые не в фокусе, остаются его частью.
| Каталог в %USERPROFILE%\WorldForge | Содержимое |
|---|---|
| projects | Сохранённые базы данных и метаданные |
| library | Vanilla index, prefabs и импортированные assets |
| cache | Декодированные наборы и производные данные для повторного использования |
| settings | Настройки, включая сохранённые данные помощника |
| export | Сгенерированные папки модов |
| conversions | Результаты и отчёты B41 |
| staging | Рабочие предпросмотры и артефакты инструментов |
При ошибке сохранения читайте status и Logs. Успешное редактирование не означает, что проект сохранён. Оставьте приложение открытым, решая проблему пути/записи; при необходимости используйте Save As в разрешённое место. Не предполагайте, что несохранённые правки пропали.
Закрытие и переключение защищены от незаметной потери несохранённого. project.lock обычно означает, что базу держит другая desktop- или MCP-сессия; корректно закройте её и повторите.
Перед экспериментом закройте проект и скопируйте его папку целиком. Сохраните нужные пользовательские assets библиотеки и запишите зависимости исходного мода. Не распространяйте всю пользовательскую папку: в ней могут быть учётные данные, извлечённая игровая графика и частная работа.
Проверка, экспорт и тестирование
Откройте Tools → Validate и прочитайте Validation. Исправьте недостающие spawn, void spawn, имена комнат, размеры парковок, water zone, отверстия в этажах и неразрешённые плитки. Чистый отчёт — только проверка редактора, не симуляция игры.
- Сохраните проект-кандидат.
- Выберите File → Export as Mod или Export на панели.
- Оставьте результат в рабочей папке экспорта и проверьте status и Logs.
- Проверьте структуру B42.20, скомпилированные ячейки, метаданные, spawn, зоны и custom dependencies.
- Держите созданный мод отдельно от редактируемого проекта.
Экспортёр записывает полные замены ячеек, не sparse runtime patches. Результат содержит скомпилированные lots и может включать static chunk scaffolding, world-map/biome-файлы, Lua metadata и custom assets. Часть исходных sidecar и динамического поведения требует отдельной обработки.
Для игрового теста скопируйте кандидата в отдельный профиль mods, включите зависимости и запустите новый мир B42.20.4. Проверьте spawn, входы, столкновения, этажи, лестницы, контейнеры, loot, парковку, воду, видимые плитки и границы ячеек. Зафиксируйте результат до объявления мода playable.
CLI/MCP smoke tools подготавливают отдельный WorldForge\smoke cachedir и checklist, но не запускают игру и не проставляют pass. См. docs/IN_GAME_SMOKE.md.
Ограничения предварительной версии
| Функция | Граница |
|---|---|
| TBX, LDtk и TMX | Поддерживаются подмножества форматов, не полный круговой обмен проектами |
| Интерчейндж | Неподдерживаемые auto-layers/image tilesets не импортируются как PZ packs |
| Экспорт B42 | Полная замена ячейки; игровая/MP-проверка не подтверждена |
| Windows x64 приложение | Нет поддерживаемой сборки редактора для Linux/macOS |
| Backend save reader | Ограниченное подмножество; законченного desktop-импорта сохранённого мира нет |
В описании development pass 25 сентября упомянуты нативные автоматические тесты и Windows desktop smoke harness, включая viewport, minimap, конвертацию и prefab town. Это свидетельство тестирования приложения и бинарной геометрии, а не проверки экспортированной карты в Project Zomboid.
Неполадки и отчёты
| Симптом | Действие |
|---|---|
| Заглушки изображений | Map → Browse install… → Decode tiles into cache; дождитесь статуса набора |
| Нет растений/объектов | Проверьте unresolved-sprite; у процедурного маркера может не быть отдельного изображения |
| Зелёные/серые замены после zoom | Проверьте релиз, повторно откройте ячейку после загрузки текстур; сообщите постоянную ошибку с координатами и скриншотом |
| Пустой экран/нет стен | Вернитесь в Cell, нажмите Work; проверьте этаж, Cut и видимость слоёв |
| Неверная minimap | Проверьте активную ячейку и этаж; переключите Mini и щёлкните по карте |
| Медленная загрузка | Переиспользуйте кэш, откройте одну ячейку, избегайте повторных Scan KY/полного импорта |
| Prefab отклонён | Проверьте препятствия, геометрию и блокировки; используйте свободную загруженную землю |
| AI выбирает не то здание | Выберите/центрируйте цель; запросите look_viewport до изменения |
| AI timeout | Остановите, проверьте завершённые правки и provider/model; повторите меньший запрос |
| Нет спрайтов мода | Добавьте оригинальные пакеты, определения и dependency IDs |
| project.lock | Закройте другую desktop/MCP-сессию проекта |
Для полезного отчёта приложите версию релиза и игры, шаги, координаты ячейки/мира, этаж, проекцию, снимок build box и текст ошибки. Не включайте API-ключи и частные данные сохранений. Декодирование и сканирование каталога затратнее повторного открытия кэшированной ячейки; Assembly снижает детализацию крупного мира.
Граница возможностей
World Forge — ранний public preview. Инструменты обмена реализуют только поддерживаемые подмножества, AI и осмотр зависят от провайдера, а экспорт представляет собой полную замену ячеек с непроверенными игровыми и сетевыми условиями. Если требуется поведение сверх этих границ, запрашивайте отдельную проверку.