moonwell-editor/docs/install.md

# Установка MoonWell Editor

Распакуйте архив в отдельную папку и откройте `benilla-editor.exe`. Rust, исходники Benilla
и исходники редактора для запуска не нужны. Требуются Windows x64, современный видеодрайвер
с поддержкой Vulkan, Microsoft Visual C++ Runtime x64 (`VCRUNTIME140.dll`) и собственная
установка WoW 1.12.1.

Это инструкция для текущего пакета. Установщик с мастером проекта, автоматическая подготовка
тестового сервера/клиента и обновления запланированы в [ROADMAP.md](ROADMAP.md), направление D.
Сейчас для Play требуется отдельно подготовленное окружение, описанное ниже.

## Первый запуск

1. Откройте общий репозиторий контента проекта в отдельной папке и выберите его JSON-проект
   в стартовом окне. Либо создайте новый проект: commit ядра и отдельный диапазон GUID
   нужно получить у владельца сервера. У разных проектов диапазоны не должны пересекаться.
2. Выберите папку WoW или её `Data`. Данные игры используются только для чтения.
3. Укажите подключение к world-базе в формате `mysql://user:password@host:port/mangos`.
   Оно нужно для каталога NPC, отображения существующих спавнов и проверки экспорта.
   Для просмотра мира без подключения можно открыть проект с уже заданными моделями.
4. Выберите папку миграций. По умолчанию это `migrations` рядом с JSON-проектом.
5. Нажмите «Сохранить настройки», затем «Открыть редактор».

Для Play нужен отдельно установленный совместимый клиент Benilla / MoonWell, подготовленный
локальный сервер vMaNGOS, выделенный GM-аккаунт и созданный персонаж. В настройках Play
укажите клиент, адрес сервера, Realm ID, аккаунт и персонажа. Скрипт `scripts/prepare-play.ps1`
предназначен для WSL с `deploy/local/compose.sh` и `apply-content.sh` нашего ядра: укажите
фактический Linux-путь ядра и порт мира. Для другого окружения используйте собственный скрипт
или применяйте миграции и перезапускайте мир вручную до Play.

Выбранный в каталоге NPC остаётся кистью для нескольких размещений. **Esc** или кнопка
**«Режим выбора (Esc)»** в каталоге отменяет размещение. После этого щёлкните по кольцу
у ног NPC, чтобы открыть его в инспекторе; щелчок по свободному месту новых NPC не создаёт.
Мир занимает свободную область между панелями и подстраивается под их размер. Обзор ПКМ,
колесо скорости и выбор поверхности работают внутри этой области.

## Где хранятся данные

- **Папка программы:** исполняемые файлы, скрипты и лицензии. Здесь нет проектов и паролей.
- **Репозиторий контента:** JSON-проекты, SQL-миграции и прочие общие файлы проекта.
  Сохраняйте их в Git этого репозитория. Файл `camp.json` из исходников редактора — локальный пример.
- **Профиль пользователя:** `settings.json`, список последних проектов и состояние Play.
  Настройки содержат локальные пароли; не добавляйте профиль в Git и не передавайте другим.
  Точный путь покажет `benilla-editor-cli.exe config-path`; он также указан в стартовом окне.
  Логи клиента и подготовки находятся в `state/play` внутри профиля данных пользователя.

Для отдельного профиля задайте абсолютный `EDITOR_HOME`: тогда используются
`<EDITOR_HOME>/config/settings.json`, `state/` и `cache/`. Относительные пути в настройках
считаются от папки `settings.json`.

Старый `.env` можно явно импортировать кнопкой стартового окна либо командой
`benilla-editor-cli.exe config-import "полный-путь-к-.env"`. Автоматического чтения `.env`
из папки программы или текущей папки больше нет. Явно заданные переменные окружения
`WOW_DATA` и `EDITOR_*` имеют приоритет над профилем при запуске.

## Создание простого квеста

Откройте «Квесты…» в верхней панели. При первом создании укажите диапазон ID квестов,
выделенный владельцем сервера для общего проекта. Нажмите «Новый квест», заполните название,
описание, цель в журнале и текст завершения. Выберите уровень и награду (опыт и медь).

Выберите роль «NPC выдачи» или «NPC сдачи», найдите NPC по имени и нажмите его в результатах.
Можно использовать выбранного в мире NPC, в том числе обычную лошадь. Ниже формы выберите
режим назначения и включите флаг «Квестодатель»:

- «Все NPC этого типа» добавляет флаг всем спавнам выбранного entry во всех патчах Vanilla,
  сохраняя остальные флаги.
- «Только выбранный NPC»: сначала выберите нужный спавн в мире, затем нажмите
  «Назначить квест только выбранному…» или включите флаг. Редактор создаст отдельный шаблон
  и переведёт на него только этот спавн. Остальные лошади останутся прежними. Для новых
  шаблонов владелец проекта один раз задаёт свободный диапазон entry в раскрывающемся блоке.

Переключатель задаёт режим следующего назначения; текущая привязка показана отдельно.
Изменения попадут в SQL-миграцию вместе с квестом и применятся при подготовке Play.
Отдельная копия сохраняет поля исходного шаблона и его существующие связи с квестами.
Пока копирование доступно для простых NPC без специальных ролей, AI/ScriptName и других
опубликованных квестов проекта. Для торговцев, тренеров и таких NPC используйте общий режим.
Новый шаблон принадлежит проекту: если впоследствии поставить ещё один спавн с его entry,
он тоже получит эти квесты. После экспорта флаг и копия сохраняются как опубликованный контент;
автоматического удаления копии или отключения опубликованного флага пока нет.
Для цели убийства переключите роль поиска, выберите существо и количество (не больше 63).
В блоке «Предметные цели и награды» выберите роль предмета и найдите его по имени (русскому
или английскому) либо entry. Поддерживаются до 4 целей сбора, до 4 фиксированных наград
и до 6 вариантов награды, из которых игрок выбирает один. Количество меняется в строке;
«Убрать» удаляет предмет из списка. При сдаче предметы цели забираются. Можно сочетать сбор
с убийствами. Без целей сбора и убийства квест завершается разговором с NPC сдачи.
Редактор проверяет наличие предметов на патче квеста и лимиты уникальности. Если один
уникальный предмет нужен для сдачи и одновременно выдаётся в награду, экспорт может быть
заблокирован: ядро проверяет возможность получить награду ещё до изъятия предметов цели.
Источники добычи и торговцы автоматически не меняются: для цели используйте предмет,
который игрок сможет получить в мире. Проверка доступности по фракции/классу и вместимости
сумок остаётся за ядром.

В блоке «Цепочка квестов» выберите предыдущий квест проекта: новый станет доступен после
его сдачи и получения награды. Можно создать несколько продолжений с одним предыдущим
квестом; это независимые доступные квесты, а не взаимоисключающие ветки.
Опция «Сразу предложить после сдачи предыдущего» включает переход к диалогу продолжения,
с учётом обычных условий ядра (например, уровня). Для неё NPC сдачи предыдущего должен
выдавать следующий квест, и патчи должны совпадать. Автоматически предлагаться может только
одно продолжение. Без этой опции продолжение выдаётся обычным способом у назначенного NPC.

Редактор показывает путь до текущего квеста и кнопки перехода к продолжениям. Циклы
и ссылки на отсутствующие квесты запрещены. Предыдущий квест с более позднего патча
блокирует экспорт и Play.
Пока цепочка связывает только собственные квесты проекта. Чтобы удалить неопубликованный
черновик, сначала уберите ссылки из его продолжений. Снятие связи и автопредложения после
экспорта создаёт новую миграцию; история прохождения персонажей при этом не сбрасывается.

Постановочные сценарии (сопровождение NPC, реплики, эмоции, волны противников) пока не
реализованы. Они выделены в ближайший этап с отдельными запусками для игрока/группы:
[архитектура сценариев](quest-scenarios.md). Связь квестов в цепочку сама по себе не запускает
такое поведение.

«Сохранить проект» сохраняет и незаконченные черновики, в том числе цепочку, в которой
вы ещё меняете NPC или патчи. Предупреждение «Цепочка» показывает, что нужно согласовать
перед проверкой сервера, экспортом и Play. «Экспорт» в панели «Изменения»
проверяет данные и создаёт общую SQL-миграцию NPC и квестов. Play использует обычный цикл
применения миграций и перезапуска локального сервера. Проверка боевого прохождения — вручную.
При обновлении текста опубликованного квеста учитывайте клиентский кеш; новый процесс Play
не равен очистке кеша у всех игроков. Для повторного прохождения используйте другого
тестового персонажа: редактор не сбрасывает историю выполненных квестов.

Пока поддержаны собственные новые квесты, разговор, убийства и сбор предметов, награды опытом,
деньгами и предметами, цепочки внутри проекта. Отдельные языковые версии запланированы в
[общем плане](ROADMAP.md); ближайший предметный этап — сценарии квестов. Опубликованный квест можно
обновлять новой миграцией; удаление доступно только неопубликованному черновику.
Проекты с квестами используют формат 2 и требуют новой версии редактора.

## Обновление

Закройте редактор и запущенный им клиент Play. Распакуйте новую версию в новую папку и
запустите её. Профиль и последние проекты сохранятся. Для Play, использующего скрипт из
старой папки программы, выберите скрипт новой версии в настройках. Общий репозиторий
контента обновляется отдельно обычным Git-процессом команды.

Автоматическая загрузка обновлений пока не реализована. Артефакты DBC/S3 относятся к
релизам игрового контента и не входят в пакет редактора.