Files
moonwell-editor/docs/STATUS.md
T
sindoring e2953c8a0d Add local Play sessions and preserve creature spawn identities
Open an owned client with an isolated local GM account, export and apply content before Play, and place its arrival point in the world. Check effective realm permissions and retain allocated guids after deletion.

Verified on Windows: fmt, workspace clippy with warnings denied, 38 workspace tests; local account_access precedence test and live wolf placement/teleport probe. Checked against Benilla aa799a2c with BENILLA_PIN_ANY=1; the pinned revision is updated separately.

Co-Authored-By: Codex <codex@openai.com>
2026-11-04 14:16:01 +04:00

23 KiB
Raw Blame History

Состояние проекта и план

Документ для того, кто продолжает работу без владельца: человека или ИИ-агента. Сначала прочитай основные принципы: PRINCIPLES.md. Правила работы описаны в ../AGENTS.md. Состояние на 2026-11-04.

Что это

benilla-editor — редактор контента для сервера vMaNGOS (WoW 1.12.1, build 5875) на движке Benilla. Мир рисуется движком Benilla поверх установленного клиента WoW. Изменения сохраняются в файл проекта (JSON) и экспортируются как миграции world-базы vMaNGOS.

Конечная цель — полноценный редактор: NPC, квесты, предметы, маршруты, DBC, клиентские патчи, новые карты. Сейчас идёт R1: визуальная расстановка NPC с безопасным экспортом.

Где что лежит

Что Где
Этот репозиторий C:\Users\sindo\benilla-editor
Benilla (движок, соседний checkout) C:\Users\sindo\benilla, закреплён коммит из BENILLA_REV (19457cb5, main)
Ядро vMaNGOS (форк владельца) WSL /home/sindo/core, рабочая ветка development
Миграции контента в ядре /home/sindo/core/sql/content/migrations/, проекты: sql/content/projects/
Локальная БД vMaNGOS Docker vmangos-local-db-1, 127.0.0.1:13306, база mangos
Установка WoW (только чтение) C:\Program Files (x86)\World of Warcraft\Data
Локальные настройки .env в корне репозитория (в git не попадает), шаблон: .env.example

Ключи .env:

  • WOW_DATA — папка установки.
  • EDITOR_WORLD_DB — mysql://vmangos:<пароль>@127.0.0.1:13306/mangos. Пароль лежит в /home/sindo/core/deploy/local/secrets/db_password.
  • EDITOR_EXPORT_DIR — путь UNC \\wsl.localhost\Ubuntu\home\sindo\core\sql\content\migrations.

Устройство кода

Крейт Что делает Bevy
editor-project Модель проекта: цель (версии Benilla и vMaNGOS), диапазон guid, спавны, baseline последнего экспорта, список экспортов с SHA-256. Сохранение побайтово стабильно. нет
editor-vmangos creature_migration: миграция в формате ядра. world_db: чтение базы (шаблоны, поиск, строки в диапазоне, audit). export: сверка с сервером и запись миграции, общая для CLI и окна. нет
editor-release Manifest релиза, схема 1 (см. release-manifest.md). нет
editor-cli benilla-editor-cli new / check / export / manifest-check. нет
editor-app Окно benilla-editor, модули ниже. да

Модули editor-app:

  • main.rs — запуск и .env. Флаги: --at x,y,z, --map, --entry, --display. Отсюда же диагностический режим EDITOR_SHOT.
  • camera.rs — свободная камера и луч курсора по поверхностям, на которых можно стоять.
  • preview.rs — модели существ. Обычные модели строятся с текстурами Monster1/2/3, гуманоиды — из модели расы, запечённой текстуры, волос, меха и геосетов. Каждый спавн стоит в анимации Stand на своём риге. Шлем, наплечники и оружие висят на якорях костей.
  • edit.rs — расстановка, выбор, перенос, поворот, высота, дубль, удаление, отмена и повтор, маркеры.
  • ui.rs — панели egui: каталог, инспектор, изменения, строка статуса. UiFocus не даёт миру перехватывать ввод над панелями.
  • server.rs — слой существующих спавнов сервера, только для чтения. Ячейки 128 ярдов в радиусе 320 ярдов от камеры читает отдельный поток со своим соединением, кадр его не ждёт.
  • play.rs, play_ui.rs — Play в отдельном окне клиента: выделенный локальный GM-аккаунт, точка старта проекта, проверка применённых миграций и необязательный скрипт подготовки. Настройка и ограничения: play.md.

Что сделано

R0 — технический прототип (закрыт, кроме проверки в игре)

  • Редактор использует только публичный API Benilla, форк патчить не пришлось. Сборка падает, если ../benilla не на коммите из BENILLA_REV. BENILLA_PIN_ANY=1 позволяет собрать всё равно, для пробы.
  • Координаты переводятся через benilla_assets::coords. Тест сверяет направление на сервере и в рендере.
  • Выбор поверхности проверен на земле и на полах WMO: 11 NPC в Штормграде, включая верхний этаж Башни магов. Отклонение 0–0,21 ярда ниже z сервера, луч остаётся на этаже NPC.
  • Миграции пишутся в формате ядра (sql/migrations/README) с id в таблице migrations, так что повторное применение ничего не делает. Таблицы world на MyISAM, отката нет, поэтому все проверки идут до первой записи:
    • новый guid должен быть свободен;
    • изменяемая или удаляемая строка должна совпадать с baseline по guid, entry и map;
    • на удаляемый спавн не должно быть ссылок в creature_addon, creature_movement, creature_linking, pool_creature, game_event_creature.
  • guid выдаются сверху вниз, от конца диапазона, и никогда не переиспользуются. Ядро даёт .npc add и временным существам номера выше MAX(creature.guid) (ObjectMgr::SetHighestGuids). После первого экспорта максимумом становится конец диапазона, и сервер выделяет номера выше него. Диапазон по умолчанию 9000000–9000999; на production его ещё нужно подтвердить.
  • Перед экспортом проект сверяется с сервером (world_db::audit). Конфликтом считаются:
    • чужая строка в диапазоне;
    • занятый guid, который проект добавляет;
    • отсутствие шаблона на patch_min спавна;
    • расхождение с последним экспортом, если все экспорты уже применены.
  • Сквозная проверка на локальном vMaNGOS прошла:
    • экспорт и применение;
    • повторное применение ничего не меняет;
    • изменение и удаление;
    • защита от занятого guid (ERROR 1644, база не тронута);
    • mangosd загружает спавны без ошибок.
  • Manifest релиза, схема 1: полный набор артефактов, потребители, неизменяемые ключи releases/<id>/ в S3, check_follows не пропустит потерю унаследованных DBC.
  • В ядре есть sql/content/, deploy/local/apply-content.sh, а init-db.sh применяет контент последним. Владелец закоммитил это в development (b32573186).

R1 — визуальная расстановка NPC (в работе)

  • Гуманоидные NPC показываются моделями: модель расы, запечённая текстура из BakedNpcTextures (она есть у всех 6984 гуманоидных display), волосы из CharSections, мех тауренов, геосеты прически и одежды. Проверено на людях, дворфе, ночных эльфах и тауренах.
  • Панели egui: каталог с поиском по базе, инспектор с отменой, список изменений с кнопками «Сохранить», «Проверить сервер», «Экспорт». Все подписи на русском.
  • CLI и окно экспортируют одним кодом (editor_vmangos::export).
  • Слой существующих спавнов сервера: модели с серо-синими кольцами. Под курсором строка статуса показывает, кто там стоит. Щелчок открывает спавн в инспекторе только для просмотра, поверх него ничего не ставится. Слой включается галочкой «спавны сервера». Учитываются спавны, которые сервер загружает на патче 10; диапазон guid проекта исключён. У аббатства Northshire прочитано 355 спавнов, прямой SQL по тем же ячейкам дал те же 355.
  • Если база недоступна, окно всё равно открывается, только без каталога и слоя. Слой переподключается, когда галочку включают снова.
  • NPC стоят в анимации Stand. Шлемы и наплечники на гуманоидах, оружие и щиты в руках: проверено на Магни (два молота), Болваре (меч и щит) и стражниках сервера.
  • 38 тестов и два opt-in теста БД: world_db::live_gear_and_box и play::live_security_matches_world_socket_realm_precedence. Windows: fmt, clippy с -D warnings и workspace tests проходят с BENILLA_PIN_ANY=1: соседний Benilla сейчас на aa799a2c, pin не менялся. Тест приоритетов прав отдельно прошёл на локальной БД, используя только временные таблицы соединения. Сборка и снимок окна были проверены при добавлении Play. Это проверка текущего checkout, а не повторная проверка закреплённой ревизии.

Play — проверка серверного контента

  • «Поставить точку Play» переводит следующий щелчок по поверхности в выбор места старта; направление берётся от камеры. Точка видна зелёным маркером, редактируется в настройках и сохраняется как необязательное поле play_start. Старые проекты читаются без изменения формата; точка не входит в SQL-diff.
  • Play сохраняет проект, проверяет локальный адрес, эффективный GM-уровень из account_access для локального RealmID 1 (его запись важнее общей -1), принадлежность персонажа и отсутствие активной сессии. Вторая сессия этого checkout блокируется файловой блокировкой ОС. Пароль передаётся только в окружении клиента.
  • Со скриптом подготовки изменения экспортируются общим кодом миграций. Стандартный scripts/prepare-play.ps1 применяет локальные миграции, перезапускает mangosd и ждёт порт мира. Без скрипта новые изменения или неприменённые экспорты блокируют Play.
  • Клиент запускается отдельным процессом; «Стоп» завершает только этот процесс. Настройки, аддон и логи изолированы в benilla-config/play/. Наследуемые инструменты WOW_* отключаются; игровой сеанс пользователя остаётся attended.
  • Аддон использует штатные API 1.12: один раз после входа нужного персонажа отправляет .gm off, затем .go xyzo с направлением и картой. В Lua-интерпретаторе Benilla проверены другой персонаж, повторное событие входа и отсутствие точки старта. Проверены блокировка сессии, передача учётных данных, совместимость старого проекта и отказ занятому аккаунту.
  • Для локального /home/sindo/core создан отдельный аккаунт EDITORPLAY (GM 3) и персонаж Playtester (человек-воин, уровень 1). Локальный .env заполнен, пароль в Git не входит. Клиент — существующий ../benilla/target/release/MoonWell.exe, подготовка — scripts/prepare-play.ps1. Права записаны в realmd.account_access, а не только в неиспользуемое серверной сессией поле account.gmlevel. Проверены SRP-вход, world handshake, перенос к сохранённой точке Play (ошибка 0 ярдов), получение живого волка guid 9000999 (entry 69, 55/55 здоровья) с сохранёнными координатами и направлением и чистый выход. Диагностика: target/play-wolf-live.log. Боевых действий проверка не выполняла.
  • Перезапуск мира сохраняет таймеры возрождения. Для guid 9000999 обнаружено сохранённое время возрождения; после его истечения подтверждён живой спавн. Выделение guid теперь хранит lowest_creature_guid и не возвращает удалённый guid после экспорта пустой baseline, чтобы новый NPC не наследовал состояние старого. Проверено после сохранения/загрузки.
  • Окно проверено диагностическим запуском без БД: панель Play, окно настроек и зелёный маркер точки старта. Снимок target/play-smoke.png, логи проверок target/play-*.log.

Что не проверено

  • Оставшаяся визуальная проверка R0. На земле перенос, координаты и направление спавна проверены по живому протоколу (см. Play выше). Для WMO поставить спавн, экспортировать, apply-content.sh, перезапустить mangosd, затем в клиенте .go xyz по строке из инспектора либо выбрать точку Play рядом со спавном и запустить клиент кнопкой Play. NPC должен стоять там же и смотреть туда же, что и стрелка. Benilla запрещает автоматические боевые прогоны (../benilla/docs/METHOD.md).
  • Действия мышью в окне: щелчки по панелям, перетаскивание в инспекторе и отмена одним шагом, кнопка «Экспорт». Код проверен снимками и тестами общих функций, но не руками.
  • Кадр из Крепости Штормграда (--at -8445,320,135) выглядит как вид изнутри стены. Похоже на положение камеры, а не на ошибку рендера, но это не разобрано.

План

Порядок внутри R1, по приоритету:

  1. Слой существующих спавнов сервера — сделан (см. выше). Он только для чтения: правка чужих спавнов означает конфликты с upstream vMaNGOS и устаревший кеш WDB у клиентов, это отдельное решение владельца. Не проверено руками: наведение, щелчок и галочка.
  2. Шлем, наплечники, оружие на гуманоидах — сделано. Шлем (с суффиксом расы и пола) и наплечники берутся из ItemDisplayInfo по внешности display. Оружие и щит берутся из снаряжения entry (world_db::creature_gear: equipment_id → creature_equip_template → item_template): основная рука в правой, вторая в левой, щит на предплечье. Дальнобойное оружие не показывается.
  3. Поза — сделано. Каждый спавн получает свой риг по схеме анимированного доодада Benilla: RigPose, AnimationPlayer с Stand по кругу, слот RigSkin::allocate_bones, риг-меши из ModelForms::require_rigged. Предметы висят на якорях костей (RigPose::anchor_for) со смещением attachment. Если слотов нет, спавн остаётся в базовой позе: у рук тогда точки в начале координат, и оружие не показывается. В Торговом квартале Штормграда 299 спавнов, все в позе, переполнения палитры нет.
  4. Мелочи:
    • выбор модели из нескольких display_id1..4 шаблона — сделано: у кисти в каталоге и у спавна в инспекторе. Это только превью: сервер сам выбирает модель по вероятностям шаблона;
    • подтверждение перед экспортом — сделано (окно Dialog::Export);
    • предупреждение при закрытии окна с несохранёнными изменениями — сделано (WindowPlugin::close_when_requested выключен, ui::close_requested);
    • ужать картинку мира до свободной области между панелями (осторожно: это рендер Benilla). Не проверено руками: щелчки по кнопкам диалогов и закрытие окна крестиком. Снимками проверено только, что окна диалогов рисуются.
  5. Критерий готовности R1: NPC расставлены в окне и видны моделями, экспортированы одной миграцией и в игре стоят там, где показывал редактор.

Следующие релизы, из исходного плана владельца:

Релиз Что
R2 Простые квесты: quest_template, связи с NPC (creature_questrelation и creature_involvedrelation), цели, награды, прохождение. Квест на убийство проверяет человек: автоматические бои запрещены.
R3 DBC: сборка, публикация в S3 по manifest, закрепление релиза, загрузка и проверка DBC перед компиляцией production-сервера. Без DBC сборка не продолжается. Схема manifest уже готова.
R4 Предметы, добыча, торговцы, диалоги, GameObject.
R5 Маршруты NPC (creature_movement), AI, события.
R6 Полётная сеть.
R7 Редактирование существующих карт (запись ADT, WMO, пересборка vmaps и mmaps).
R8 Новые карты, подземелья и рейды: простые части без механик боссов (см. PRINCIPLES.md). Как программировать механики боссов, владелец ещё не решил.
R9+ Заклинания, таланты, профессии, репутация, мировые события, транспорт, PvP.

Правила, которые действуют дальше:

  • Меняешь имя или текст существующего entry — клиенты со старым кешем WDB его не увидят. Нужен новый entry или clearClientCache в manifest.
  • Строки vMaNGOS привязаны к диапазонам патчей. Экспорт всегда выставляет patch_min и patch_max явно.
  • Код vMaNGOS под GPL. Редактор (MIT/Apache) читает схему и генерирует SQL, но код ядра не линкует.
  • DBC, MPQ и всё, что собрано из файлов установки, хранится только в S3 и никогда не попадает в Git.