diff --git a/docs/plan-v2.md b/docs/plan-v2.md new file mode 100644 index 0000000..0ea4bc2 --- /dev/null +++ b/docs/plan-v2.md @@ -0,0 +1,302 @@ +# Bevy Forge v2 — план live-редактора + +Статус: план на согласование. Работа начинается с M0, не с «полного редактора». +Репозиторий: https://git.shanaty.ru/Emil_Shanaty/Bevy_Forge + +## 1. Цель + +Сделать **встроенный live-редактор сцен для Bevy 0.20**: реальный ECS, реальный рендер, +иерархия, reflection-инспектор, selection/transform, gizmo, сохранение сцены и BSN-экспорт. + +Это не клон Unity и не полный IDE. Это сфокусированный редактор сцен/уровней, который +работает внутри игры и переиспользует уже готовый core v1. + +## 2. Жёсткие решения + +- **Bevy 0.20**, Rust 2021. +- **Никакого egui** и связанных крейтов: `egui`, `eframe`, `bevy_egui`, `egui_dock`, + `bevy-inspector-egui`, `bevy_editor_pls`, BIRP, `transform-gizmo`. +- UI — **родной Bevy UI**: + - `bevy_ui`; + - официальный `bevy_ui_widgets` 0.20 (button, checkbox, text input, list, menu, + dialog, modal, popover, radio, scroll area, slider, tabs); + - `bevy_text`, `bevy_input_focus`. +- Иерархия, инспектор, gizmo, docking/tree (позже) — **свой код**. +- v1 (standalone) не ломать. Новый редактор — отдельный crate в том же workspace. +- Внешние редакторские проекты не добавлять как зависимости. `bevy_ui_widgets` — + официальная часть Bevy, а не сторонний редактор. +- v1 пока остаётся на egui как legacy. В v2 egui не должно быть даже транзитивно. + +## 3. Что уже есть + +- `crates/bevy_forge_core` — сцены `.forge.ron`, компоненты, валидация, codegen BSN/Rust, + project/config/history/assets. +- `crates/bevy_forge_editor` — standalone v1 на eframe/egui. +- `crates/bevy_forge_cli` — `forge` CLI, scaffold, validate/export. +- `compat/bsn-smoke` — компиляция сгенерированного BSN против реального Bevy 0.20. +- `examples/demo-project` — 2D/3D сцены и текстуры. +- Тесты: `cargo test --workspace` — 346 passed, 1 ignored; baseline зелёный. +- Документация: `README.md`, `docs/architecture.md`, `docs/format.md`, `docs/bsn-export.md`. + +Переиспользовать: core-модель, `.forge.ron`, валидацию, codegen, CLI, demo, лицензии. +Не переписывать: формат сцены, сериализацию, BSN-кодогенерацию без отдельного контракта. + +## 4. Архитектура v2 + +``` +Bevy Forge v2 +├── crates/bevy_forge_runtime # новый live-плагин +│ ├── src/lib.rs # EditorPlugin, EditorState +│ ├── src/plugin.rs # режимы, системы, регистрация +│ ├── src/ui/ # Bevy UI: панели, тема, виджеты +│ ├── src/hierarchy.rs # ListBox, Children/ChildOf, selection +│ ├── src/inspector.rs # reflection-инспектор, свои виджеты +│ ├── src/gizmo.rs # transform gizmo, picking +│ ├── src/screenshot.rs # deterministic screenshot mode +│ └── examples/editor_spike.rs # demo app +├── crates/bevy_forge_core # переиспользуется +├── crates/bevy_forge_editor # v1 legacy, не ломать +└── crates/bevy_forge_cli # переиспользуется +``` + +### EditorPlugin + +- `EditorState`: `Enabled/Disabled`, `Selection`, `Mode` (`Edit/Paused/Play` позже). +- `EditorPlugin` добавляется в игру; в релизе выключается feature-флагом. +- UI-панели — обычные Bevy UI ноды, фиксированная раскладка: + - слева hierarchy; + - справа inspector; + - снизу/сверху toolbar и status; + - центр — viewport (игра). +- Docking не делать в M0. Позже — свои tabs/split panes. +- Инспектор читает `Reflect`/`TypeRegistry`; компоненты без `Reflect` показываются + read-only/`Debug`. +- Gizmo — свой, на Bevy Gizmos + picking; не тащить `transform-gizmo`. +- Screenshot — встроенный deterministic mode: размер окна, ожидание кадров, PNG, exit. +- Scene save/load — через существующий core; BSN export — существующий codegen. +- Code editor (Helix/Vim) — **не в M0**. Сначала внешний запуск, встроенный PTY-терминал + отдельным milestone. + +### Контракты M0 + +Зафиксировать до кода: + +```rust +pub struct EditorPlugin; +pub struct EditorState { /* enabled, selection, ... */ } +pub struct Selection(pub Option); + +pub trait InspectorSource { + fn reflect_component(&self, entity: Entity) -> Option<&dyn Reflect>; +} +``` + +Плагины модулей регистрируются в `lib.rs` заранее: + +```rust +.add_plugins((HierarchyPlugin, InspectorPlugin, GizmoPlugin, ScreenshotPlugin)) +``` + +T01 создаёт заглушки `HierarchyPlugin`/`InspectorPlugin`/`GizmoPlugin`, чтобы T02–T04 +не редактировали один `lib.rs`. + +## 5. Scope и non-goals + +### Входит в v2 core + +- live иерархия и selection; +- reflection-инспектор для Transform/Name/Visibility и примитивных полей; +- translate gizmo (позже rotate/scale); +- editor camera; +- save/load сцены `.forge.ron`; +- BSN export; +- undo/redo; +- play/pause; +- asset browser (базовый); +- deterministic screenshots; +- документация и тесты. + +### Не входит + +- modeling/скульптинг (это Blender); +- полноценный code IDE внутри UI; +- multi-world/полный Unity play mode; +- сетевой collaborative editing; +- поддержка всех кастомных компонентов без `Reflect`; +- встроенный терминальный редактор в M0–M3; +- миграция v1 на Bevy UI в этом плане (v1 остаётся legacy). + +## 6. Milestones и бюджет + +Бюджет — **верхняя оценка**, а не обещание. Считать по фактическим токенам и запросам. +Ориентир: прямой `deepseek-flash`, off-peak, без Polza. + +| Milestone | Результат | Запросы | Output | Ожидаемо | Hard cap | +|---|---|---:|---:|---:|---:| +| **M0 Spike** | plugin + UI shell + hierarchy + inspector + один gizmo + screenshot | 200–300 | 0.3–0.5M | **$1.5–2.5** | **$2.5** | +| **M1 Core** | selection, transform, undo/redo, save/load, editor camera | 400–700 | 0.8–1.5M | **$2.5–5** | **$5** | +| **M2 Live** | play/pause, assets, real render, BSN export, file watch | 500–900 | 1.0–2.0M | **$2.5–5** | **$5** | +| **M3 Hardening** | tests, UX, sizes, docs, performance | 300–600 | 0.6–1.2M | **$1–3** | **$3** | +| **Итого core** | | **1 400–2 500** | **2.7–5.2M** | **$7.5–14** | **$15.5** | + +Отдельно, только после core: + +| Опция | Оценка | +|---|---:| +| Внешний запуск Helix/Vim + file watch | **$0.5–1** | +| Встроенный PTY-терминал (Helix/Vim) | **$4–8**, 600–1000 запросов | +| Neovim RPC backend | **$3–6** | + +Правило: milestone не начинается, пока предыдущий не принят verifier'ом и не записан +фактический расход. + +## 7. M0 — детальный план + +### Состав + +- Lead: workspace, manifest, docs, integration, final gate. +- Implementer A: T01 runtime shell + T02 hierarchy. +- Implementer B: T03 inspector + T04 gizmo/screenshot (после T01 contract). +- Verifier V01: независимая проверка, без участия в коде. +- Максимум 2 implementer'а + 1 verifier. **Не swarm.** + +### Задачи + +| ID | Задача | Write scope | Зависит | +|---|---|---|---| +| LEAD | workspace manifest, пример, docs M0, интеграция | `Cargo.toml`, `docs/m0-spike.md`, `crates/bevy_forge_runtime/examples/**` | — | +| T01 | runtime crate, `EditorPlugin`, UI shell, тема, заглушки плагинов | `crates/bevy_forge_runtime/Cargo.toml`, `src/lib.rs`, `src/plugin.rs`, `src/ui/**` | — | +| T02 | hierarchy ListBox, Children/ChildOf, selection, scroll | `src/hierarchy.rs` | T01 | +| T03 | reflection-инспектор: Name, Transform, Visibility, primitives | `src/inspector.rs` | T01 | +| T04 | editor camera, translate gizmo, deterministic screenshot | `src/gizmo.rs`, `src/screenshot.rs` | T01 | +| V01 | независимая проверка M0 | `.swarm/reviews/**` (вне продукта) | T01–T04 | + +T01 сначала коммитит каркас, контракты и заглушки плагинов; только после этого B начинает +T03/T04. Каждый implementer добавляет focused-тесты для своего модуля; LEAD запускает +общий gate. Не делить один `lib.rs` между T02–T04. + +### M0 acceptance + +- [ ] `cargo check -p bevy_forge_runtime` — без ошибок. +- [ ] `cargo test -p bevy_forge_runtime` — тесты зелёные. +- [ ] `cargo tree -p bevy_forge_runtime -i egui` — пусто/ошибка «package not found». +- [ ] `cargo tree -p bevy_forge_runtime -i bevy_egui` — пусто. +- [ ] `cargo run -p bevy_forge_runtime --example editor_spike` — открывается, + editor toggle работает. +- [ ] Hierarchy показывает сущности сцены; клик меняет selection. +- [ ] Inspector показывает Name/Transform/Visibility; изменение `Translation.x` + применяется к ECS и видно в gizmo. +- [ ] Gizmo отображается и двигает выбранную сущность (хотя бы translate). +- [ ] Screenshot mode сохраняет PNG в 1440×900 и 1000×640. +- [ ] Нет изменений в core/v1, кроме необходимых shared manifest (LEAD). +- [ ] README/`docs/m0-spike.md` описывают запуск и ограничения. + +### M0 verification + +V01 получает diff, acceptance-команды и скриншоты. Не читает отчёт Implementer'а как истину. +Проверяет: + +- отсутствие egui в дереве runtime-крейта; +- реальный запуск и два скриншота; +- selection → inspector → ECS; +- gizmo; +- отсутствие out-of-scope правок; +- читаемость кода и отсутствие «заглушек вместо функционала». + +### M0 stop-rules + +Остановиться и вернуться к плану, если: + +- 70% cap израсходовано, а acceptance не собран; +- output >0.5M или запросов >300; +- средний input >80k на запрос; +- egui всё же попал в dependency tree; +- hierarchy/inspector требуют переписывать core; +- verifier нашёл критический дефект архитектуры, а не отдельный баг. + +## 8. M1–M3 — кратко + +### M1 Core +- selection API и multi-select (если дёшево); +- Transform editing с undo/redo (command stack); +- save/load `.forge.ron` через core; +- editor camera: pan/zoom/orbit; +- горячие клавиши: delete, duplicate, focus, save; +- unit-тесты на selection/undo/save; +- без docking и без терминала. + +### M2 Live +- play/pause без потери сцены (snapshot/restore); +- asset browser: список файлов, превью, drag в сцену; +- реальный рендер сцены, не wireframe; +- BSN export из UI; +- file watcher и hot reload; +- базовая валидация сцены. + +### M3 Hardening +- размеры 1440×900, 1280×720, 1000×640; +- keyboard/focus/IME; +- пустые/ошибочные состояния; +- производительность hierarchy/inspector; +- README, `docs/editor.md`, лицензии; +- финальный независимый review. + +## 9. Токен-бюджет и процесс + +- Новый чат на каждый milestone. Не тащить историю v1. +- 2 implementer'а + 1 verifier на M0/M1; 3+1 на M2; без 30 агентов. +- Файлы до ~800 строк; если больше — split до dispatch. +- Targeted tests; полный `cargo test --workspace` — только lead на финале. +- Freeze перед verify; после фиксов — delta-review, не полный re-review. +- Кэш: стабильный префикс system/tools/skills; не менять без причины. +- Off-peak: после 13:00 МСК, до 04:00, выходные. +- `max_tokens` и `reasoning_effort: low` для механических задач. +- Прямой API, `deepseek-flash`; не Polza. +- Бюджет записывать в `state.json`/`budget.md`: requests, input hit/miss, output, USD. + +### Stop-rules (общие) + +- 70% cap без принятого milestone → стоп. +- output >2k/запрос или input >80k/запрос → пересобрать контекст. +- verifier rejection >30% → проблема в брифах/контрактах. +- Появился egui/сторонний редактор в runtime-крейте → стоп и убрать. + +## 10. Открытые вопросы + +1. `bevy_ui_widgets` — официальная часть Bevy 0.20, не сторонний редактор. Оставляем? + Если нет — делаем кнопки/поля/списки полностью вручную; это дороже. +2. v1 оставляем legacy на egui или потом отдельно мигрируем/удаляем? + В v2 egui не используется в любом случае. +3. Linux-first? Скриншоты/запуск сначала на Linux, потом macOS/Windows. +4. Ветка `v2-live-editor`; main не ломаем. +5. Нужен ли full docking в v2.0 или фиксированные панели достаточно? + По плану — фиксированные панели; docking позже. + +## 11. Промпт для нового чата + +```text +Прочитай docs/plan-v2.md в репозитории Bevy_Forge и начни с M0 Spike. + +Repo: https://git.shanaty.ru/Emil_Shanaty/Bevy_Forge +Ветка: v2-live-editor. v1 не ломать, core/codegen/CLI переиспользовать. + +Сначала: +1. Prerequisite gate: rust/cargo, Bevy 0.20, display/screenshot; ничего не устанавливать + без разрешения; если чего-то нет — спросить. +2. Прочитать README, docs/architecture.md, docs/plan-v2.md, Cargo.toml. +3. Показать 5–6 задач M0 с write scope, acceptance и оценкой запросов. +4. Дождаться подтверждения, затем делать. + +Ограничения: +- никакого egui/eframe/bevy_egui/egui_dock/bevy-inspector-egui/bevy_editor_pls/BIRP; +- UI только Bevy UI + официальный bevy_ui_widgets 0.20; +- hierarchy/inspector/gizmo — свой код; +- M0: plugin + UI shell + hierarchy + Name/Transform/Visibility inspector + + один translate gizmo + screenshot 1440×900 и 1000×640; +- cap $2.5, 200–300 запросов, ≤0.5M output; direct deepseek-flash, off-peak; +- 2 implementer'а + 1 verifier, без swarm; +- остановиться на 70% cap или при появлении egui в дереве. + +После M0: отчёт с фактическими requests/input/output/USD, скриншотами и вердиктом +verifier'а. Не начинать M1 без принятого M0. +```