Files
moonwell-editor/docs/STATUS.md
T
sindoring 5e4d5ffa05 Hand-off notes: status, plan and working rules
docs/STATUS.md records what is done (R0, R1 so far), what is unverified (the in-game check, mouse
interaction in the window), and the plan from R1's remaining steps through R9. AGENTS.md (pulled
into CLAUDE.md) holds the checks, the diagnostic run, the pin and repository rules, and the
Windows/WSL pitfalls met so far.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 12:56:53 +04:00

14 KiB
Raw Blame History

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

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

Что это

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, гуманоиды — из модели расы, запечённой текстуры, волос, меха и геосетов.
  • edit.rs — расстановка, выбор, перенос, поворот, высота, дубль, удаление, отмена и повтор, маркеры.
  • ui.rs — панели egui: каталог, инспектор, изменения, строка статуса. UiFocus не даёт миру перехватывать ввод над панелями.

Что сделано

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).
  • 30 тестов, clippy с -D warnings чистый.

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

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

План

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

  1. Слой существующих спавнов сервера. Строки creature вокруг камеры показываются полупрозрачными маркерами или моделями. Читать их пачками по тайлу или радиусу через world_db, без блокировки кадра: сейчас запросы к БД синхронные в главном потоке, для поиска это терпимо, для потока спавнов уже нет. Только для чтения. Правка чужих спавнов означает конфликты с upstream vMaNGOS и устаревший кеш WDB у клиентов, это отдельное решение владельца.
  2. Шлем, наплечники, оружие на гуманоидах. Модели предметов берутся из ItemDisplayInfo (NpcAppearance.equipment[0..1]) и крепятся к точкам на модели. Оружие NPC задаёт сервер (creature_equip_template), читать его из базы.
  3. Поза. Сейчас модели стоят в базовой позе. Нужен хотя бы первый кадр анимации Stand.
  4. Мелочи:
    • выбор модели из нескольких display_id1..4 шаблона;
    • подтверждение перед экспортом;
    • предупреждение при закрытии окна с несохранёнными изменениями;
    • ужать картинку мира до свободной области между панелями (осторожно: это рендер 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 Новые карты и подземелья.
R9+ Заклинания, таланты, профессии, репутация, мировые события, транспорт, PvP.

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

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