Bevy_Forge/docs/architecture.md

# Bevy Forge architecture

This page describes how the Bevy Forge workspace is put together: the crates, the scene model, the
editor's panel/action model, persistence, code generation and the testing strategy. It documents the
architecture the code is being built against; individual modules may still be in progress in a given
checkout.

- Product overview and quick start: [README](../README.md)
- Scene file reference: [Scene format](format.md)
- Export templates: [BSN export](bsn-export.md)

## Design constraints

1. **No Bevy dependency in the editor.** `bevy_forge_core` and `bevy_forge_editor` depend only on
   serde/RON/IndexMap/thiserror/toml in core and eframe/egui/image in the editor. The only crate that
   links Bevy is the excluded `compat/bsn-smoke` verification crate. This keeps editor builds fast
   and independent of Bevy's release cadence.
2. **Export is source code.** A `.forge.ron` scene stores editor data only. BSN or imperative Rust
   is generated on demand and never stored in the scene file. Code generation is deterministic for a
   given document and options.
3. **One scene format.** `.forge.ron` (RON via serde) is the only scene extension. It is Forge's own
   format, not Bevy's `.scn.ron` dynamic-scene format.
4. **Snapshot undo.** The document is small enough that full snapshots are simpler and safer than
   inverse operations. Every undoable mutation goes through one session API.
5. **Immediate-mode UI with deferred actions.** Panels render and return `Action` values. Only the
   app shell performs file I/O, spawning, saving and exporting.

## Workspace at a glance

```text
                  +--------------------------------+
                  |        bevy_forge_core         |
                  |  model - project - validation  |
                  |  history - assets - codegen    |
                  +---------------+----------------+
                                  ^
                    depends on    |    depends on
             +--------------------+--------------------+
             |                                         |
+------------+-------------+              +------------+-------------+
|   bevy_forge_editor      |              |     bevy_forge_cli       |
|  eframe/egui application |              |  clap binary `forge`     |
|  binary: `bevy-forge`    |              |                          |
+--------------------------+              +--------------------------+

  compat/bsn-smoke (excluded from the workspace, depends on Bevy 0.20.0)
  compiles representative generated BSN to prove the export is valid Rust.
```

| Crate / directory | Role | Binary / artifact |
|---|---|---|
| `crates/bevy_forge_core` | Document model, structural ops, project and scene persistence, undo, asset index, validation, code generation | library |
| `crates/bevy_forge_editor` | Native editor (eframe/egui): panels, viewports, dialogs, palette, toasts | `bevy-forge` |
| `crates/bevy_forge_cli` | `forge new`, `validate`, `export`, `info`, `scenes` | `forge` |
| `examples/demo-project` | Real Bevy 0.20 project used as the first-run demo and screenshot subject | not built by the workspace |
| `compat/bsn-smoke` | Compiles generated BSN against real Bevy 0.20.0; excluded from the workspace | standalone crate |
| `scripts/` | End-to-end generated-code check | shell script |

The root `Cargo.toml` declares the three workspace members and excludes `compat/bsn-smoke` so Bevy
is never built as part of the normal workspace.

## Core model

All types below are public and frozen for this release.

| Type | Module | Meaning |
|---|---|---|
| `EntityId` (`u64`) | `scene` | Stable entity identity inside one scene file |
| `SceneDoc` | `scene` | `format_version`, `name`, ordered `entities`, ordered `roots`, `next_id` |
| `EntityNode` | `scene` | `id`, `name`, `parent`, ordered `children`, mandatory `transform`, `components`, editor-only `locked` |
| `Transform` | `math` | `translation: Vec3`, `rotation: Vec3` (XYZ Euler **degrees**), `scale: Vec3` |
| `ComponentData` | `components` | Tagged enum of built-in components plus `Custom(CustomComponent)` |
| `Session` | `history` | Document + undo/redo history + dirty flag |
| `History` / `Snapshot` | `history` | Bounded stack of full-document snapshots (default limit 100) |
| `Project` | `project` | Root, package name, Bevy version, assets dir; scene load/save/list |
| `AssetIndex` / `AssetEntry` / `AssetKind` | `assets` | Recursive index of the project's asset files |
| `ValidationReport` / `Issue` / `Severity` | `validation` | Deterministic validation output |
| `ExportFormat` / `CodegenOptions` | `codegen` | Export dispatch and options (function name, header) |
| `EditorConfig` | `config` | Recent projects and editor preferences |

### Scene identity and ordering

- IDs are `u64`, start at 1 and are never reused within a scene; `next_id` is monotonic.
- Each entity has exactly one parent (`None` for roots). Cycles are rejected by `reparent`.
- `roots` and every `children` vector define display order and are preserved by save/load.
- `SceneDoc::entities` is an `IndexMap`; insertion order is stable for serialization.
- `EntityNode.id` must equal its map key; `SceneDoc::check_integrity()` reports mismatches, dangling
  parents/children, duplicate references and wrong root/child links.
- Every structural edit must leave `check_integrity() == []`.
- `locked` is editor-only metadata: it blocks viewport transforms, not deletion or hierarchy edits.

### Transform semantics

`Transform.rotation` stores XYZ Euler angles in degrees because that is what the inspector edits.
Hierarchy composition converts degrees to a quaternion (`quat_from_euler_deg`), composes parent and
child, and converts back to Euler degrees. Export converts the other way with
`Quat::from_euler(EulerRot::XYZ, x.to_radians(), y.to_radians(), z.to_radians())`. There is no
ambiguity between "editor degrees" and "Bevy radians" because conversion only happens at the
composition and code-generation boundaries.

`Name` and `Transform` are node fields in `.forge.ron`, not entries in `components`; the BSN and Rust
generators always emit them for every entity.

### Components

`ComponentData` is a serde-tagged enum:

- `Sprite(SpriteData)`, `Text2d(Text2dData)`, `Camera2d`, `Camera3d`,
  `PointLight(PointLightData)`, `DirectionalLight(DirectionalLightData)`, `Mesh3d(Mesh3dData)`,
  `Visibility(VisibilityMode)`, `Custom(CustomComponent)`.
- `ComponentData::key()` is the uniqueness key: `"sprite"`, `"text2d"`, `"camera2d"`, `"camera3d"`,
  `"point_light"`, `"directional_light"`, `"mesh3d"`, `"visibility"`, and
  `"custom:<type_path>"`. `add_component` refuses duplicate keys; custom components are unique per
  type path, so two different custom types can coexist.
- `Mesh3dData` holds `MeshSource` (`Primitive(PrimitiveShape)` or `Asset(String)`) and
  `MaterialData`. Primitives are cuboid, sphere, plane, cylinder and capsule.
- `CustomComponent` stores a Rust type path plus a list of `(name, expr)` fields. Expressions are
  raw Rust/BSN text, validated only for identifier shape and non-emptiness.

## Undo/redo

`Session` wraps the document and owns the history:

```rust
// One undo entry, recorded only if the document actually changed.
session.edit("Rename entity", |doc| {
    doc.rename(id, "Player");
});

// Continuous interactions (gizmo drags): snapshot before, mutate every frame,
// commit once on release.
let before = session.doc().clone();
// ... update transforms during the drag ...
session.commit(before, "Move entities");
```

- `edit` clones the document before running the closure and records a snapshot only when the result
  differs.
- `commit` accepts a caller-supplied pre-edit snapshot and records it once at the end of a drag.
- `doc_mut` is the escape hatch for read-modify-write UI code: it marks the session dirty but adds
  no undo point, so it must not be used for user-visible edits.
- `undo`/`redo` swap snapshots and return the action label; the app puts that label in the status
  bar.
- `mark_saved` clears the dirty flag, `replace` swaps in a new document and clears history (used
  when opening or creating a scene), and `is_dirty` drives the title dot, autosave and quit guard.
- A new edit clears the redo stack. The default history limit is 100 snapshots.

## Persistence

### Opening a project

`Project::open(root)` requires an existing directory with a `Cargo.toml` containing a `bevy`
dependency (normal, workspace or dev dependencies; a string or a `{ version = ... }` table). It
canonicalizes the root, reads the package name, and records the Bevy version string. The assets
directory is `<root>/assets` when it exists, otherwise `<root>` (so projects without a dedicated
assets folder still work).

Scenes live in `<root>/scenes/*.forge.ron`. `Project::load_scene` parses RON and normalizes a legacy
`format_version: 0` to the current version in memory. `Project::save_scene` accepts an optional
path (defaulting to a slugified scene name), refuses paths outside the project root, creates parent
directories, serializes with the pretty RON printer and writes atomically: a temporary file
`.<name>.tmp-<pid>` in the target directory, then `rename` over the destination.

### Autosave and configuration

When autosave is enabled (`autosave_secs > 0`, default 60), the app writes a dirty document to the
project's `.forge/autosave.forge.ron` no more often than that interval. Autosave never marks the
session saved and never replaces an explicit save; `.forge/` is ignored by version control.

Editor preferences (recent projects, last project, grid/snap/show-assets flags, autosave interval)
are stored as RON in the platform config directory, honouring `XDG_CONFIG_HOME` on Unix:
`<config>/bevy-forge/config.ron`.

## Assets and validation

`AssetIndex::scan(assets_dir)` recursively indexes regular files under the assets directory, skipping
hidden entries, symlinks, and `target` / `build` / `node_modules` directories, with a depth cap.
Paths are `/`-separated and relative to the assets directory and are sorted for determinism. Files
are classified by extension into `Image`, `Mesh`, `Audio`, `Font`, `Scene`, `Shader`, `Material` and
`Other`. A missing or unreadable assets directory yields an empty index with an `error` string; the
editor shows that state instead of failing.

`validate_scene(doc, assets: Option<&AssetIndex>) -> ValidationReport` runs structural checks,
range checks and (only when an index is supplied) asset existence/kind checks. Severities order as
`Info < Warning < Error`; the report offers `is_ok`, `errors`, `warnings`, `count`, `by_entity` and
`sorted`. Validation must never panic on malformed forests and is deterministic (severity
descending, then entity, then message). See [the format reference](format.md#validation) for the
rule list.

## Code generation

```rust
pub enum ExportFormat { Bsn, Rust }

pub struct CodegenOptions {
    pub function_name: String, // a Rust identifier that is not a keyword
    pub include_header: bool,
}
```

The dispatch method is `ExportFormat::generate(self, doc: &SceneDoc, options: &CodegenOptions) ->
Result<String, CodegenError>`, implemented in `codegen.rs` and forwarded to `codegen::bsn` or
`codegen::rust`.

- `codegen.rs` owns the shared options and dispatch; `codegen/bsn.rs` emits Bevy 0.20 BSN and
  `codegen/rust.rs` emits imperative `Commands::spawn` code.
- Both generators walk roots and children in document order and emit `Name` and `Transform` for every
  entity, followed by components in stored order.
- Generation is pure: no file access, no globals, no timestamps. The same document and options
  produce identical text.
- Errors are explicit: `EmptyScene`, `InvalidIdentifier`, `NonFinite` (transform, material or light
  value) and `InvalidCustomComponent`. Invalid scenes must not panic the generator.
- The BSN generator conditionally adds asset parameters (`meshes`, `materials`) to the function
  signature, based on what the document uses, and chooses `bsn!` (single root, `impl Scene`) or
  `bsn_list!` (multiple roots, `impl SceneList`).
- The CLI and editor are thin wrappers around `generate`: the CLI prints to stdout or writes `-o`;
  the editor shows a preview, can copy to the clipboard and can save to a file.

## Editor shell

`ForgeApp` owns all long-lived state: `Session`, `UiState`, `Project`, `AssetIndex`, `TextureCache`,
`Toasts`, `EditorConfig`, `ExportState`, every panel state and the current scene path. Panels never
own the document.

### Frame order

Each frame, `ForgeApp` builds a borrowed `EditorContext` and runs, in order:

1. `menu::show` - top menu bar.
2. `shortcuts::handle` - global keyboard shortcuts.
3. `status_bar::show` - counts, selection, dirty state, mode, cursor position.
4. `assets_panel::show` - asset browser (side panel).
5. `hierarchy::show` / `inspector::show` - left/right side panels when visible.
6. The central panel: `viewport2d::show` or `viewport3d::show` according to the view mode.
7. `palette::show`, then `dialogs::show` - overlays.
8. The collected `Vec<Action>` is dispatched by the app; autosave runs afterwards.

Menus, shortcuts, panels and dialogs all return actions instead of performing operations.

### Context and panels

```rust
pub struct EditorContext<'a> {
    pub session: &'a mut Session,
    pub project: Option<&'a Project>,
    pub assets: &'a AssetIndex,
    pub textures: &'a mut TextureCache,
    pub ui: &'a mut UiState,
    pub toasts: &'a mut Toasts,
    pub export: &'a mut ExportState,
}
```

```text
// Frozen panel entry points (types abridged; see the module sources).
hierarchy::show(ctx: &egui::Context, cx: &mut EditorContext<'_>, state: &mut HierarchyPanelState) -> Vec<Action>
inspector::show(ctx: &egui::Context, cx: &mut EditorContext<'_>, state: &mut InspectorPanelState) -> Vec<Action>
assets_panel::show(ctx: &egui::Context, cx: &mut EditorContext<'_>, state: &mut AssetsPanelState) -> Vec<Action>
viewport2d::show(ui: &mut egui::Ui, cx: &mut EditorContext<'_>, state: &mut Viewport2dState) -> Vec<Action>
viewport3d::show(ui: &mut egui::Ui, cx: &mut EditorContext<'_>, state: &mut Viewport3dState) -> Vec<Action>
menu::show(ctx: &egui::Context, cx: &EditorContext<'_>) -> Vec<Action>
palette::show(ctx: &egui::Context, cx: &mut EditorContext<'_>, state: &mut PaletteState) -> Vec<Action>
dialogs::show(ctx: &egui::Context, cx: &mut EditorContext<'_>, state: &mut DialogsState) -> Vec<Action>
welcome::show(ctx: &egui::Context, state: &mut WelcomeState, config: &EditorConfig) -> Vec<Action>
shortcuts::handle(ctx: &egui::Context, session: &Session) -> Vec<Action>
status_bar::show(ctx: &egui::Context, cx: &EditorContext<'_>)
```

Rules that keep panels independent and testable:

- Selection changes are immediate (`cx.ui.selection.select_only/add/toggle/...`); app-level
  operations become actions.
- Scene mutations go through `cx.session.edit(...)` (or snapshot + `commit` for drags).
- Panels never save files, spawn processes, open dialogs themselves or change the active screen.
- Each panel owns a `Default`-constructible state struct stored by `ForgeApp`.
- Input focus is not stolen except by the command palette and dialogs.
- User feedback uses `cx.ui.status` for routine messages and `cx.toasts` for successes/errors.

### Actions

`Action` (in `action.rs`) is the vocabulary between UI and app. It covers scene lifecycle (new,
open, save, save-as), export (BSN/Rust, copy, write), editing (undo, redo, duplicate, delete,
focus), view state (2D/3D, grid, snap, panels, fit), and shell operations (palette, shortcuts,
about, quit, reload assets). `ForgeApp::handle_actions` is the only place that executes them.
Adding an action is a shared-contract change: the variant must be added to `action.rs` and handled
in `app.rs`, never handled inside a panel.

### UI state

`UiState` holds multi-selection (ordered set plus a primary entity), view mode, panel visibility,
grid/snap settings, per-panel search strings and asset filter, cursor world position, viewport
rectangle, status text, error banner and the one-frame `fit_view_requested` flag. Panel-specific
state (zoom, pan, drag origins, inline-rename buffer, filters, dialog fields) stays in that panel's
own state struct.

## Error handling and robustness

- Core errors are `thiserror` enums (`SceneError`, `ProjectError`, `CodegenError`, `ConfigError`).
  User input, file I/O and RON parsing never use `unwrap()`/`expect()`.
- Editor failures are surfaced as toasts or an error banner and leave the previous state usable;
  opening a malformed scene must not panic the app.
- CLI user errors are printed to stderr with a non-zero exit code; no panics.
- Asset scanning and texture loading are failure-safe: missing files produce empty/placeholder
  states, not crashes.
- Structural operations and validation bound parent-chain walks so malformed forests cannot hang
  the UI.

## Testing strategy

The project separates pure logic from UI and from real-Bevy compilation so each layer can fail
independently:

| Layer | What it proves | Mechanism |
|---|---|---|
| Core unit tests | Model, hierarchy, undo, project, config, assets, validation, both generators | `#[cfg(test)]` modules and `crates/bevy_forge_core/tests/` |
| CLI tests | Argument parsing, exit codes, file output, JSON shape | `std::process::Command` with `env!("CARGO_BIN_EXE_forge")` and `tempfile` project fixtures |
| Editor tests | Panels render and emit the expected actions without a window | Headless `egui::Context` frames driving `ForgeApp::new_for_test` / `ForgeApp::ui` and panel functions |
| Generated-code gate | Exported BSN is valid Rust against Bevy 0.20.0 | `compat/bsn-smoke` (`cargo check`) plus `scripts/check-generated-code.sh` |
| Manual/visual | The actual desktop app is usable and looks intentional | Launch with the demo project and capture `docs/screenshot.png` |

Representative commands (run inside a checkout):

```bash
cargo test -p bevy_forge_core
cargo test -p bevy_forge_cli
cargo test -p bevy_forge_editor
cargo check --workspace
cd compat/bsn-smoke && cargo check
```

Snapshot assumptions are asserted directly: tests create documents through the public structural API
and check `check_integrity()`, round-trip scenes through RON, compare undo/redo states, and compare
generated text against expected templates. The generated-code gate is the only test that links Bevy,
which is why it lives in an excluded crate.

## Non-goals

- No live in-game editor plugin, remote protocol or hot reload in 0.1.
- No Bevy dependency in the editor or core crates (and therefore no Bevy types in the scene model).
- No runtime `.bsn` asset format; BSN is generated Rust source.
- No animation editor, `bevy_ui` editor, material graph, terrain tools, collaboration or asset import
  pipeline.
- No GPU-rendered viewport; the 3D view is an egui-painted preview.
- No support for Bevy versions other than 0.20 BSN, and no legacy `.scn.ron` dynamic scenes.
- No native file dialogs.

## Extension points

- **New built-in component.** Add a `ComponentData` variant plus its data struct, a `ComponentKind`
  entry and `key`, default construction, asset references, validation rules, both generator arms,
  the inspector's add/remove UI and tests. This is a contract change because `ComponentData` is
  frozen.
- **New primitive shape.** Extend `PrimitiveShape` and `half_extents`, emit the verified Bevy
  constructor in the BSN/Rust generators, and add inspector fields. Verify the constructor against
  Bevy 0.20 before documenting it.
- **New export format.** Add an `ExportFormat` variant, a generator module and dispatch arm, a CLI
  value, an editor menu entry and compile/test coverage.
- **New panel or action.** Panels follow the `show(...) -> Vec<Action>` pattern and keep their state
  in a `Default` struct owned by `ForgeApp`. New actions require editing `action.rs` and handling
  them in `app.rs`; panels must not acquire file I/O.
- **New CLI command.** Add a clap subcommand in `crates/bevy_forge_cli`, reuse core APIs, define exit
  codes, and add process tests.
- **Project-specific components.** Prefer the custom-component escape hatch over adding built-ins:
  store a type path and raw field expressions, and document the required derives. This keeps the
  editor independent of game code.
- **Asset kinds.** Extend `AssetKind::from_path` and the asset filter when a new file type needs
  first-class browsing.

Public signatures are frozen for this release. Changing one requires updating the contract and all
call sites rather than editing a panel in isolation.

## Further reading

- [Scene format](format.md) - the `.forge.ron` reference.
- [BSN export](bsn-export.md) - templates, derive requirements, Bevy integration.
- [README](../README.md) - quick start, CLI, shortcuts, limitations.