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