303 lines
16 KiB
Markdown
303 lines
16 KiB
Markdown
# 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<Entity>);
|
||
|
||
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.
|
||
```
|