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 требуется отдельно подготовленное окружение, описанное ниже.

## Запуск перед приёмкой из исходников

Для общего запуска локального прототипа из папки checkout выполните
`./scripts/start-editor.ps1 -WithRuntime`. Скрипт собирает текущий release с `Cargo.lock`,
подготавливает изолированный тестовый сервер, проверяет его порты из Windows и открывает
редактор с отдельным профилем подключения к его БД. Предпосылки WSL/Docker и входные данные
описаны в [отчёте D0](d0-runtime.md). Имя окружения задаётся через `-RuntimeName`.
После закрытия редактора сервер продолжает работать. Для остановки используется
`./scripts/d0-runtime.ps1 -Action down -Name mw-editor-d0-local`.

Для запуска редактора отдельно выполните `./scripts/start-editor.ps1`. Для сборки нужны
Rust/Cargo с Windows MSVC toolchain и Visual Studio Build Tools с C++/Windows SDK.
При первом запуске сборки нужен доступ к закреплённым зависимостям.

Для повторного запуска готового release используйте `-NoBuild`. Отдельный профиль:
`./scripts/start-editor.ps1 -ProfileDirectory 'C:/Editor acceptance/profile'`.
Аргументы редактора передаются массивом, например
`-EditorArguments @('C:/Content project/camp.json', '--at', '-8935,-129.5,84')`.
Относительные пути считаются от текущей папки PowerShell. После закрытия окна скрипт
возвращает код редактора и восстанавливает прежний `EDITOR_HOME`.

В режиме `-WithRuntime` профиль по умолчанию создаётся в
`%LOCALAPPDATA%/MoonWell/Editor/d0/<имя окружения>`. `-ProfileDirectory` в этом режиме
принимает пустой каталог или ранее созданный профиль того же окружения. Путь к собственным
ресурсам можно задать через `-WowDataDirectory`; при первом запуске используется доступный
путь из обычных настроек. Настройки подключения генерируются автоматически. Пароль хранится
в локальном `config/settings.json`, как в обычном профиле редактора. Этот файл содержит
секрет и предназначен для локального использования.

`scripts/package.ps1` собирает Windows x64 ZIP из фактической папки Cargo
(включая `CARGO_TARGET_DIR`). В распакованном пакете `scripts/start-editor.ps1` запускает
поставленный exe без Rust; основной способ запуска пакета — открыть `benilla-editor.exe`.
Этот запуск проверяет редактор и настройки; подготовка сервера и Play описаны отдельно.

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

1. Выберите JSON общего проекта либо создайте локальный проект. Обычный авторинг не требует
   вручную выбирать ID. Совместимость ядра и границы ID спавнов доступны в дополнительных
   настройках; занятость проверяется перед экспортом. Для командного выпуска согласуйте
   целевое окружение и общие ID проекта.
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.

Каталог существ сразу показывает карточки: листайте страницы, фильтруйте по типу и уровню
или ищите имя. Щелчок по карточке открывает настоящую 3D-модель из ресурсов клиента.
Кнопка **«Разместить выбранное существо»** включает кисть для нескольких размещений. **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 этого типа» добавляет флаг всем спавнам выбранного entry во всех патчах Vanilla,
  сохраняя остальные флаги.
- «Только выбранный NPC» выбран по умолчанию. Редактор создаст отдельный шаблон с автоматическим
  ID и переведёт на него только этот спавн. Остальные NPC этого типа останутся прежними.

Переключатель задаёт режим следующего назначения; текущая привязка показана отдельно.
Назначение меняет только выбранную роль. Для одинаковой выдачи и сдачи назначьте обе роли.
На шаге наград каталог предметов открывается без запроса, показывает клиентские иконки,
категории, качество и уровень. Выберите цель сбора, фиксированную награду или вариант на выбор,
затем нажмите имя нужного предмета. Источники добычи автоматически не создаются.
На шаге проверки нажмите «Проверить проект»: ошибки и следующий шаг появятся в этом же окне.
После сохранения экспортируйте миграцию через «Изменения». Экспорт фиксирует историю:
Undo/Redo применяются к правкам, сделанным после последнего экспорта.
Локальные ID не являются глобальной бронью. Если ID занял другой автор, экспорт будет
отклонён; черновик останется в проекте. Автоматического объединения независимых проектов пока нет.
Изменения попадут в 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 относятся к
релизам игрового контента и не входят в пакет редактора.