# 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:"`. `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 `/assets` when it exists, otherwise `` (so projects without a dedicated assets folder still work). Scenes live in `/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 `..tmp-` 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: `/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`, 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` 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 inspector::show(ctx: &egui::Context, cx: &mut EditorContext<'_>, state: &mut InspectorPanelState) -> Vec assets_panel::show(ctx: &egui::Context, cx: &mut EditorContext<'_>, state: &mut AssetsPanelState) -> Vec viewport2d::show(ui: &mut egui::Ui, cx: &mut EditorContext<'_>, state: &mut Viewport2dState) -> Vec viewport3d::show(ui: &mut egui::Ui, cx: &mut EditorContext<'_>, state: &mut Viewport3dState) -> Vec menu::show(ctx: &egui::Context, cx: &EditorContext<'_>) -> Vec palette::show(ctx: &egui::Context, cx: &mut EditorContext<'_>, state: &mut PaletteState) -> Vec dialogs::show(ctx: &egui::Context, cx: &mut EditorContext<'_>, state: &mut DialogsState) -> Vec welcome::show(ctx: &egui::Context, state: &mut WelcomeState, config: &EditorConfig) -> Vec shortcuts::handle(ctx: &egui::Context, session: &Session) -> Vec 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` 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.