How renzora/engine works
1. Repository shape: a Rust monorepo of plugins
- The repo is organized as a workspace with a small root application/CLI and many crates/renzora_* packages.
- Most packages are Bevy plugins or plugin pairs: a runtime crate plus an optional editor/ companion crate.
- This means the architecture is intentionally modular: systems can be composed, swapped, or omitted rather than being hard-wired into one engine binary.
2. Top-level product model
- The project is both a game engine and a visual editor.
- The runtime side is the actual engine/game executable.
- The editor side adds tooling, inspectors, previews, panels, and authoring workflows around the same runtime data model.
- The README makes clear the editor and runtime are separate launch modes, but share the same engine/plugin ecosystem.
3. Command-line and build orchestration
- The root src/main.rs plus Docker-related files indicate a CLI named renzora.
- Its job is project scaffolding, running editor/runtime builds, cross-compiling, testing, plugin management, and shell access.
- Architecture-wise, the CLI is the outermost control plane; it does not contain the engine itself, but orchestrates builds and packaging around it.
4. Core engine layer
- crates/renzora_engine, crates/renzora_runtime, crates/renzora_scene, crates/renzora_input, crates/renzora_settings, crates/renzora_globals, and crates/renzora_undo form the base engine/runtime support.
- These crates handle scene loading, virtual file access, camera/runtime viewport behavior, input mapping, settings, autoloads, and undo/redo.
- This layer is the foundation used by both the editor and the game runtime.
5. Asset pipeline and import/export boundary
- crates/renzora_import, crates/renzora_rpak, crates/renzora_asset_registry, crates/renzora_asset_browser, and crates/renzora_engine/src/asset_reader.rs form the content ingestion path.
- The repo supports many source formats: models, scenes, scripts, graphs, materials, particles, textures, and archives.
- A typical flow is: external asset files → import/conversion/packing → registry/browser/indexing → runtime/editor consumption.
- renzora_rpak is the packaging/archive boundary, while renzora_import handles format normalization.
6. Editor framework and authoring UI
- crates/renzora_editor, crates/renzora_editor_framework, crates/renzora_ui, crates/renzora_ember, and crates/renzora_game_ui form the editor UI stack.
- renzora_ember is the low-level widget/markup system; renzora_ui adds docking/tabs/windows; renzora_editor_framework provides editor conventions like cameras, commands, settings, and thumbnail registries.
- Higher-level editor tools such as the hierarchy, inspector, scene browser, code editor, material editor, particle editor, terrain editor, etc. build on this shared UI layer.
7. Viewport-centric editing model
- crates/renzora_viewport is the main bridge between authored content and the visible scene.
- It handles drag-and-drop into the viewport, play mode, external runtime integration, viewport settings, and debug rendering hooks.
- The viewport is where scene assets, materials, particles, and gizmos converge for live editing and preview.
8. Rendering and graphics extensions
- The repo is heavily graphics-oriented: many crates are standalone rendering effects or material systems, each with WGSL shaders.
- crates/renzora_shader is the shader/material authoring and codegen layer, supporting multiple backends and material graphs.
- crates/renzora_lumen, crates/renzora_rt, crates/renzora_oit, crates/renzora_outline, crates/renzora_postprocess, and the many post-processing crates implement specialized render passes and effects.
- The architecture here is “render core + optional feature plugins,” not one monolithic renderer.
9. Gameplay and simulation plugins
- Several crates provide domain systems that plug into ECS rather than owning the app loop: audio, physics, animation, cloth, water, terrain, foliage, navigation, mesh editing, procedural trees, and more.
- Examples include renzora_audio, renzora_physics, renzora_animation, renzora_terrain, renzora_water, renzora_navmesh, renzora_gizmo, and renzora_mesh_edit.
- These subsystems typically expose components, systems, resources, and editor panels, so they can participate in both runtime and tooling.
10. Scripting and visual logic
- crates/renzora_scripting is the main script host with Lua and Rhai backends, HTTP support, commands, input, reflection, and execution systems.
- crates/renzora_blueprint and crates/renzora_blueprint_editor provide visual graph scripting.
- crates/renzora_script_variables and crates/renzora_macros support binding data into scripts and reflection-driven tooling.
- The main data flow is engine state ↔ script/runtime bindings ↔ editor inspection/authoring.
11. Networking, multiplayer, and platform services
- crates/renzora_network implements client/server/protocol/RPC/prediction and has tests for host server behavior.
- crates/renzora_auth, renzora_hub, renzora_export, renzora_splash, and renzora_websocket_plugin connect the engine to platform/account/marketplace/export workflows.
- These crates sit at the edge of the engine, bridging the local runtime with external services or packaged deployment pipelines.
12. XR, mobile, and platform-specific runtime paths
- crates/bevy_oxr provides OpenXR/WebXR-facing support crates, including OpenXR session, graphics, and utility layers.
- Platform adaptation is also visible in renzora_android, renzora_ios, renzora_shell, and the templates/ directory for Android/iOS/Web packaging.
- The architecture is cross-platform by design, with platform-specific code isolated behind dedicated crates and templates.
13. Content and authoring assets are first-class
- assets/ contains the engine’s own example/content library: materials, particles, shaders, UI templates, scripts, locale files, and previews.
- This repository is not just code; it ships a large catalog of sample content that exercises the engine’s rendering, UI, scripting, and gameplay systems.
- Those assets are important in the diagram because they demonstrate the same import/render/UI pipeline used for end-user projects.
14. Operational/tooling layer
- CI workflows, Dockerfiles, devcontainer support, docs versions, and templates show a strong emphasis on reproducible builds and multi-platform distribution.
- The build system is part of the architecture: containerized compilation, cross-target packaging, and generated templates are core to how the engine is delivered.
- In diagrams, this should appear as an outer build/release layer feeding platform-specific artifacts rather than as part of the runtime game loop.
Main entry points: src/lib.rs Editor Framework · src/lib.rs Engine Core · src/lib.rs Runtime App · src/lib.rs Scene I/O
Components 31
Control Plane
CLI, scaffolding, build, and packaging orchestration
- renzora CLI · Top-level command-line control plane for scaffolding, builds, tests, and packaging
src/main.rs
Engine Core
Runtime foundation shared by editor and game execution
- Runtime App · Root crate that assembles runtime/editor launch modes and plugin wiring
crates/renzora/src/lib.rs - Engine Core · Core engine services and shared runtime primitives
crates/renzora_engine/src/lib.rs - Scene I/O · Scene loading, VFS access, autoloads, crash handling, and asset reading
crates/renzora_scene/src/lib.rs - Runtime Shell · Runtime viewport scaling and stretch behavior for the executable
crates/renzora_runtime/src/lib.rs - Input Maps · Action mapping and input state used by runtime and editor tools
crates/renzora_input/src/lib.rs - Settings · Persistent settings and editor/runtime configuration state
crates/renzora_settings/src/lib.rs - Undo Stack · Undo/redo infrastructure shared by editor authoring workflows
crates/renzora_undo/src/lib.rs
Content Pipeline
Import, packing, registry, and asset consumption path
- Assets · Repository-provided example content, shaders, UI templates, scripts, and previews
assets - Import · Format normalization and conversion for meshes, scenes, materials, textures, and USD/FBX/glTF sources
crates/renzora_import/src/lib.rs - RPAK · Archive format and packing boundary for distributable content
crates/renzora_rpak/src/lib.rs - Asset Registry · Indexed asset metadata consumed by editor browsers and runtime systems
crates/renzora_asset_registry/src/lib.rs - Asset Browser · Asset browsing and thumbnail presentation for authored content
crates/renzora_asset_browser/src/lib.rs
Editor Stack
UI, viewport, and authoring tools layered over the engine
- Editor App · Top-level editor application crate and launch integration
crates/renzora_editor/src/lib.rs - Editor Framework · Editor conventions for commands, cameras, settings, inspectors, and thumbnails
crates/renzora_editor_framework/src/lib.rs - UI Stack · Docking, windows, panels, trees, and drag/drop UI infrastructure
crates/renzora_ui/src/lib.rs - Ember UI · Low-level markup, reactive bindings, inspectors, widgets, and style/theme layers
crates/renzora_ember/src/lib.rs - Viewport · Bridge between authored content and live scene preview, play mode, and debug rendering
crates/renzora_viewport/src/lib.rs - Hierarchy · Entity tree, selection, and scene organization controls
crates/renzora_hierarchy/src/lib.rs - Inspector · Property editing and reflection-driven inspection surfaces
crates/renzora_inspector/src/lib.rs - Code Editor · Script browsing, highlighting, and code editing panels
crates/renzora_code_editor/src/lib.rs - Material Editor · Graph-based material authoring, preview, and inspection
crates/renzora_material_editor/src/lib.rs
Simulation Plugins
Gameplay, rendering, and ECS-driven feature plugins
- Shader System · Shader backends, material graphs, codegen, and runtime material resolution
crates/renzora_shader/src/lib.rs - Render Ext · Postprocess and rendering feature plugins such as Lumen, outline, OIT, AA, bloom, fog, and tone mapping
crates/renzora_lumen/src/lib.rs - Game Systems · Domain plugins for audio, physics, animation, terrain, water, navmesh, gizmos, and related simulation
crates/renzora_physics/src/lib.rs - Scripting · Lua/Rhai scripting host, bindings, command execution, reflection, and HTTP helpers
crates/renzora_scripting/src/lib.rs - Blueprints · Graph-based visual scripting compiler and interpreter plus editor support
crates/renzora_blueprint/src/lib.rs
Platform Edge
Network, platform services, XR, and export/runtime targets
- Network · Client/server networking, RPC, prediction, protocol, and replication support
crates/renzora_network/src/lib.rs - Platform Services · Authentication, hub, export, shell, websocket, splash, and marketplace-adjacent workflows
crates/renzora_auth/src/lib.rs - XR · OpenXR/WebXR runtime support and headset-facing integration layers
crates/bevy_oxr/crates/bevy_xr/src/lib.rs - Export · Template-based export, signing, download, and platform packaging workflows
crates/renzora_export/src/lib.rs
Connections 33
- renzora CLI → Runtime App: launches · CLI orchestrates runtime/editor commands and project actions
- renzora CLI → Export: packages · Build and packaging commands feed platform exports
- renzora CLI → Platform Services: orchestrates · CLI also drives shell, hub, and service workflows
- Runtime App → Engine Core: uses · Root runtime is built on shared engine services
- Runtime App → Scene I/O: uses · Runtime depends on scene loading and virtual file system support
- Engine Core → Input Maps: consumes · Engine systems read shared input mappings and actions
- Engine Core → Settings: reads · Engine and editor configuration comes from shared settings
- Engine Core → Undo Stack: tracks · Authoring workflows rely on undo/redo history
- Scene I/O → Assets: reads · Scene and asset loading ultimately consume repository content
- Scene I/O → Import: ingests · Scene I/O connects to normalized imported assets
- Import → RPAK: packs · Imported content can be packaged for distribution
- RPAK → Asset Registry: publishes · Packed content is indexed for lookup and consumption
- Asset Registry → Asset Browser: feeds · Registry metadata powers the browser and thumbnails
- Editor App → Editor Framework: boots · Editor app is assembled from the shared editor framework
- Editor App → UI Stack: hosts · Editor app uses docking and panel infrastructure
- UI Stack → Ember UI: builds on · Higher-level UI composes low-level widget and markup primitives
- Editor Framework → Viewport: configures · Framework configures the main editing viewport and cameras
- Editor Framework → Inspector: supports · Framework provides inspector conventions and reflection helpers
- Editor Framework → Hierarchy: supports · Framework supports scene organization and selection panels
- Editor Framework → Asset Browser: supports · Framework provides thumbnail and browser integration
- Editor Framework → Code Editor: supports · Framework integrates code editing and script tooling
- Editor Framework → Material Editor: supports · Framework integrates material authoring workflows
- Viewport → Scene I/O: previews · Viewport renders and interacts with scene data
- Viewport → Render Ext: routes · Viewport routes debug and feature rendering effects
- Material Editor → Shader System: authors · Material editor sits on top of shader graph and codegen
- Scripting → Blueprints: complements · Script host and visual graphs cover complementary logic paths
- Scripting → Engine Core: binds · Scripting binds engine state and commands into runtime execution
- Blueprints → Engine Core: extends · Visual logic extends the engine ECS/runtime model
- Game Systems → Engine Core: plugs into · Gameplay and simulation plugins attach to the engine core
- Network → Game Systems: syncs · Networking complements gameplay systems with replication and prediction
- Platform Services → Network: depends on · Platform services integrate with multiplayer and external APIs
- XR → Runtime App: targets · XR support is a runtime path for alternate display modes
- Export → Runtime App: packages · Export builds bundle the runtime for target platforms