# 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.
```