# babylonjs/editor architecture

> Architecture diagram of the GitHub repository babylonjs/editor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/babylonjs/editor
- Repository: https://github.com/babylonjs/editor
- Video tour (about a minute): https://gitdiagram.com/babylonjs/editor/video

## Overview

#### Purpose and entry points
Babylon.js Editor 5 is a cross-platform Electron desktop editor for authoring Babylon.js 3D scenes, assets, scripts, rendering settings, and exports. Its primary application entry surfaces are the Electron/editor bootstrap and React UI: `editor/src/index.ts`, `editor/src/electron/events/editor.ts`, and `editor/src/editor/main.tsx`. Root build orchestration is `build.mjs`; the repository uses Yarn Classic and TypeScript.

#### Desktop process boundary
The editor separates Electron main-process responsibilities—window lifecycle, native dialogs, shell integration, export IPC, OAuth, custom protocols, and model-conversion workers—from renderer-side authoring UI. Core boundary paths are `editor/src/electron/events/window.ts`, `editor/src/electron/events/export.ts`, and `editor/src/electron/protocol.ts`. Renderer code uses IPC-facing utilities rather than directly owning native capabilities; native dependencies including `node-pty` and Assimp support require platform-native builds.

#### Scene authoring and interactive UI
The renderer is a large React/TypeScript workspace organized around a persistent editor layout, Babylon scene preview, hierarchy/graph, inspector, asset browser, animation/cinematic tools, navmesh, and ragdoll workflows. Primary composition paths are `editor/src/editor/layout.tsx`, `editor/src/editor/layout/preview.tsx`, and `editor/src/editor/layout/inspector.tsx`. Commands and inspector controls mutate the in-memory Babylon scene; common operations are centralized under `editor/src/project/add/` and `editor/src/tools/`.

#### Project persistence, import, and export pipeline
Projects are stored as editor scene/assets structures and reconstructed through staged loading plugins. Load flow prepares a scene, loads its configuration/resources, then installs typed plugins for cameras, meshes, materials, animation, particles, skeletons, and related entities: `editor/src/project/load/load.tsx`, `editor/src/project/load/scene.ts`, and `editor/src/project/load/plugins/meshes.ts`. Save/export serializes the scene and assets, including textures, materials, physics, LODs, scripts, and KTX/KTX2 options: `editor/src/project/save/scene.ts`, `editor/src/project/export/export.tsx`, and `editor/src/project/export/assets.ts`.

#### Runtime library and generated applications
`tools/` is the reusable runtime-facing Babylon.js support library used by exported projects: decorators/scripts, scene loading, asset/database/container loading, rendering pipelines, physics, and cinematic playback. Its public entry and key stages are `tools/src/index.ts`, `tools/src/loading/loader.ts`, and `tools/src/cinematic/cinematic.ts`. Templates package editor-authored assets with starter applications for Electron, Next.js, Nuxt, Solid, and vanilla JS; representative paths are `templates/electron/src/electron/main.mts`, `templates/nextjs/src/app/page.tsx`, and `templates/vanillajs/src/main.ts`.

#### CLI, automation, and integrations
The CLI performs headless project packaging/export work, gathering scene resources and processing assets/textures, including KTX/KTX2, with optional S3 integration: `cli/bin/babylonjs-editor-cli.js`, `cli/src/pack/pack.mts`, and `cli/src/s3/s3.mts`. MCP is a separate Node-side tool server that translates agent tool requests into editor actions; the transport/tool contract spans `mcp/src/index.mts`, `mcp/src/request.mts`, and editor-side `editor/src/mcp/mcp.ts`. Marketplace integrations target AmbientCG, Poly Haven, Sketchfab, plus optional FAB and Quixel plugins: `editor/src/tools/marketplaces/registrations.ts`, `plugins/fab/src/index.tsx`, and `plugins/quixel/src/index.ts`.

#### Website and distribution
`website/` is a separate Next.js marketing, documentation, download, and experiment/conversion application, not the editor runtime. Its key entry/API boundaries are `website/src/app/page.tsx`, `website/src/app/api/converter/route.ts`, and `website/src/app/renderer.tsx`. Download URLs point to DigitalOcean Spaces; website conversion endpoints invoke Assimp/Blender-oriented conversion code. Platform packaging produces signed or unsigned Electron artifacts and must run on compatible OS environments because of native modules.

Main entry points: [`editor/src/project/export/export.tsx`](https://github.com/babylonjs/editor/blob/master/editor/src/project/export/export.tsx) (Project export), [`editor/src/editor/layout.tsx`](https://github.com/babylonjs/editor/blob/master/editor/src/editor/layout.tsx) (Persistent editor layout), [`editor/src/electron/events/editor.ts`](https://github.com/babylonjs/editor/blob/master/editor/src/electron/events/editor.ts) (Main-process events), [`tools/src/index.ts`](https://github.com/babylonjs/editor/blob/master/tools/src/index.ts) (Tools runtime library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Electron Editor"]
  node_bootstrap["Editor bootstrap<br/>Electron entry<br/>[index.ts]"]
  node_main_events["Main-process events<br/>Electron main<br/>[editor.ts]"]
  node_window_events["Window lifecycle<br/>Electron main<br/>[window.ts]"]
  node_export_ipc["Export IPC<br/>Electron main<br/>[export.ts]"]
  node_protocol["Custom protocol<br/>Electron main<br/>[protocol.ts]"]
  node_renderer["React editor root<br/>Renderer entry<br/>[main.tsx]"]
end

subgraph group_authoring["Authoring &amp; Projects"]
  node_layout["Persistent editor layout<br/>React workspace<br/>[layout.tsx]"]
  node_preview["Babylon scene preview<br/>React panel<br/>[preview.tsx]"]
  node_inspector["Inspector<br/>React panel<br/>[inspector.tsx]"]
  node_commands["Scene commands &amp; tools<br/>Authoring operations"]
  node_project_load["Project loader<br/>Load pipeline<br/>[load.tsx]"]
  node_scene_load["Scene reconstruction<br/>Load stage<br/>[scene.ts]"]
  node_mesh_plugin["Mesh loading plugin<br/>Load plugin<br/>[meshes.ts]"]
  node_scene_save["Scene serialization<br/>Save pipeline<br/>[scene.ts]"]
  node_project_export["Project export<br/>Export pipeline<br/>[export.tsx]"]
  node_export_assets["Asset export<br/>Export stage<br/>[assets.ts]"]
end

subgraph group_runtime["Export Runtime"]
  node_runtime_lib["Tools runtime library<br/>Babylon runtime<br/>[index.ts]"]
  node_runtime_loader["Runtime scene loader<br/>Runtime stage<br/>[loader.ts]"]
  node_cinematic["Cinematic playback<br/>Runtime feature<br/>[cinematic.ts]"]
  node_templates["Application templates<br/>Generated app starters<br/>[main.ts]"]
end

subgraph group_automation["Automation &amp; Integrations"]
  node_cli{{"Headless CLI<br/>Node CLI"}}
  node_cli_pack["CLI pack pipeline<br/>Packaging stage<br/>[pack.mts]"]
  node_mcp_server{{"MCP tool server<br/>Node server<br/>[index.mts]"}}
  node_mcp_bridge["Editor MCP bridge<br/>Editor integration<br/>[mcp.ts]"]
  node_marketplaces["Marketplace registrations<br/>Integration registry<br/>[registrations.ts]"]
end

subgraph group_web["Website"]
  node_website["Website app<br/>Next.js app<br/>[page.tsx]"]
  node_converter_api["Conversion API<br/>Next.js route<br/>[route.ts]"]
end

node_bootstrap -->|"starts"| node_main_events
node_main_events -->|"manages"| node_window_events
node_main_events -->|"registers"| node_export_ipc
node_main_events -->|"registers"| node_protocol
node_bootstrap -->|"launches"| node_renderer
node_renderer -->|"renders"| node_layout
node_layout -->|"hosts"| node_preview
node_layout -->|"hosts"| node_inspector
node_layout -->|"uses"| node_commands
node_commands -->|"initiates export"| node_project_export
node_project_load -->|"loads"| node_scene_load
node_scene_load -->|"installs"| node_mesh_plugin
node_project_load -->|"hydrates scene"| node_layout
node_commands -->|"persists"| node_scene_save
node_scene_save -->|"serializes for"| node_project_export
node_project_export -->|"processes"| node_export_assets
node_project_export -.->|"uses native export"| node_export_ipc
node_project_export -->|"packages into"| node_templates
node_templates -->|"depends on"| node_runtime_lib
node_runtime_lib -->|"provides"| node_runtime_loader
node_runtime_lib -->|"provides"| node_cinematic
node_cli -->|"runs"| node_cli_pack
node_cli_pack -.->|"headless packaging"| node_project_export
node_mcp_server -->|"sends requests"| node_mcp_bridge
node_mcp_bridge -->|"executes actions"| node_commands
node_marketplaces -->|"imports assets"| node_commands
node_website -->|"calls"| node_converter_api

click node_bootstrap "https://github.com/babylonjs/editor/blob/master/editor/src/index.ts"
click node_main_events "https://github.com/babylonjs/editor/blob/master/editor/src/electron/events/editor.ts"
click node_window_events "https://github.com/babylonjs/editor/blob/master/editor/src/electron/events/window.ts"
click node_export_ipc "https://github.com/babylonjs/editor/blob/master/editor/src/electron/events/export.ts"
click node_protocol "https://github.com/babylonjs/editor/blob/master/editor/src/electron/protocol.ts"
click node_renderer "https://github.com/babylonjs/editor/blob/master/editor/src/editor/main.tsx"
click node_layout "https://github.com/babylonjs/editor/blob/master/editor/src/editor/layout.tsx"
click node_preview "https://github.com/babylonjs/editor/blob/master/editor/src/editor/layout/preview.tsx"
click node_inspector "https://github.com/babylonjs/editor/blob/master/editor/src/editor/layout/inspector.tsx"
click node_project_load "https://github.com/babylonjs/editor/blob/master/editor/src/project/load/load.tsx"
click node_scene_load "https://github.com/babylonjs/editor/blob/master/editor/src/project/load/scene.ts"
click node_mesh_plugin "https://github.com/babylonjs/editor/blob/master/editor/src/project/load/plugins/meshes.ts"
click node_scene_save "https://github.com/babylonjs/editor/blob/master/editor/src/project/save/scene.ts"
click node_project_export "https://github.com/babylonjs/editor/blob/master/editor/src/project/export/export.tsx"
click node_export_assets "https://github.com/babylonjs/editor/blob/master/editor/src/project/export/assets.ts"
click node_runtime_lib "https://github.com/babylonjs/editor/blob/master/tools/src/index.ts"
click node_runtime_loader "https://github.com/babylonjs/editor/blob/master/tools/src/loading/loader.ts"
click node_cinematic "https://github.com/babylonjs/editor/blob/master/tools/src/cinematic/cinematic.ts"
click node_templates "https://github.com/babylonjs/editor/blob/master/templates/vanillajs/src/main.ts"
click node_cli "https://github.com/babylonjs/editor/blob/master/cli/bin/babylonjs-editor-cli.js"
click node_cli_pack "https://github.com/babylonjs/editor/blob/master/cli/src/pack/pack.mts"
click node_mcp_server "https://github.com/babylonjs/editor/blob/master/mcp/src/index.mts"
click node_mcp_bridge "https://github.com/babylonjs/editor/blob/master/editor/src/mcp/mcp.ts"
click node_marketplaces "https://github.com/babylonjs/editor/blob/master/editor/src/tools/marketplaces/registrations.ts"
click node_website "https://github.com/babylonjs/editor/blob/master/website/src/app/page.tsx"
click node_converter_api "https://github.com/babylonjs/editor/blob/master/website/src/app/api/converter/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootstrap,node_main_events,node_window_events,node_export_ipc,node_protocol,node_renderer toneBlue
class node_layout,node_preview,node_inspector,node_commands,node_project_load,node_scene_load,node_mesh_plugin,node_scene_save,node_project_export,node_export_assets toneAmber
class node_runtime_lib,node_runtime_loader,node_cinematic,node_templates toneMint
class node_cli,node_cli_pack,node_mcp_server,node_mcp_bridge,node_marketplaces toneRose
class node_website,node_converter_api toneIndigo
```

## Components

### Electron Editor

Desktop main and renderer processes.

- [Editor bootstrap](https://github.com/babylonjs/editor/blob/master/editor/src/index.ts): Electron entry · `editor/src/index.ts`
- [Main-process events](https://github.com/babylonjs/editor/blob/master/editor/src/electron/events/editor.ts): Electron main · Registers editor-level native capabilities. · `editor/src/electron/events/editor.ts`
- [Window lifecycle](https://github.com/babylonjs/editor/blob/master/editor/src/electron/events/window.ts): Electron main · `editor/src/electron/events/window.ts`
- [Export IPC](https://github.com/babylonjs/editor/blob/master/editor/src/electron/events/export.ts): Electron main · Bridges renderer export requests to native work. · `editor/src/electron/events/export.ts`
- [Custom protocol](https://github.com/babylonjs/editor/blob/master/editor/src/electron/protocol.ts): Electron main · `editor/src/electron/protocol.ts`
- [React editor root](https://github.com/babylonjs/editor/blob/master/editor/src/editor/main.tsx): Renderer entry · `editor/src/editor/main.tsx`

### Authoring & Projects

Scene editing and persistence pipeline.

- [Persistent editor layout](https://github.com/babylonjs/editor/blob/master/editor/src/editor/layout.tsx): React workspace · Composes authoring panels and tools. · `editor/src/editor/layout.tsx`
- [Babylon scene preview](https://github.com/babylonjs/editor/blob/master/editor/src/editor/layout/preview.tsx): React panel · `editor/src/editor/layout/preview.tsx`
- [Inspector](https://github.com/babylonjs/editor/blob/master/editor/src/editor/layout/inspector.tsx): React panel · `editor/src/editor/layout/inspector.tsx`
- **Scene commands & tools**: Authoring operations · Mutate the in-memory Babylon scene.
- [Project loader](https://github.com/babylonjs/editor/blob/master/editor/src/project/load/load.tsx): Load pipeline · Prepares scenes and installs typed loading stages. · `editor/src/project/load/load.tsx`
- [Scene reconstruction](https://github.com/babylonjs/editor/blob/master/editor/src/project/load/scene.ts): Load stage · `editor/src/project/load/scene.ts`
- [Mesh loading plugin](https://github.com/babylonjs/editor/blob/master/editor/src/project/load/plugins/meshes.ts): Load plugin · Representative typed entity loader. · `editor/src/project/load/plugins/meshes.ts`
- [Scene serialization](https://github.com/babylonjs/editor/blob/master/editor/src/project/save/scene.ts): Save pipeline · `editor/src/project/save/scene.ts`
- [Project export](https://github.com/babylonjs/editor/blob/master/editor/src/project/export/export.tsx): Export pipeline · Packages serialized scenes and assets. · `editor/src/project/export/export.tsx`
- [Asset export](https://github.com/babylonjs/editor/blob/master/editor/src/project/export/assets.ts): Export stage · Processes textures and export asset options. · `editor/src/project/export/assets.ts`

### Export Runtime

Runtime library and generated applications.

- [Tools runtime library](https://github.com/babylonjs/editor/blob/master/tools/src/index.ts): Babylon runtime · Reusable support library consumed by exports. · `tools/src/index.ts`
- [Runtime scene loader](https://github.com/babylonjs/editor/blob/master/tools/src/loading/loader.ts): Runtime stage · `tools/src/loading/loader.ts`
- [Cinematic playback](https://github.com/babylonjs/editor/blob/master/tools/src/cinematic/cinematic.ts): Runtime feature · `tools/src/cinematic/cinematic.ts`
- [Application templates](https://github.com/babylonjs/editor/blob/master/templates/vanillajs/src/main.ts): Generated app starters · Targets Electron and web frameworks. · `templates/vanillajs/src/main.ts`

### Automation & Integrations

Headless, agent, and marketplace integrations.

- [Headless CLI](https://github.com/babylonjs/editor/blob/master/cli/bin/babylonjs-editor-cli.js): Node CLI · Packages projects and processes assets. · `cli/bin/babylonjs-editor-cli.js`
- [CLI pack pipeline](https://github.com/babylonjs/editor/blob/master/cli/src/pack/pack.mts): Packaging stage · `cli/src/pack/pack.mts`
- [MCP tool server](https://github.com/babylonjs/editor/blob/master/mcp/src/index.mts): Node server · Translates agent requests into editor actions. · `mcp/src/index.mts`
- [Editor MCP bridge](https://github.com/babylonjs/editor/blob/master/editor/src/mcp/mcp.ts): Editor integration · `editor/src/mcp/mcp.ts`
- [Marketplace registrations](https://github.com/babylonjs/editor/blob/master/editor/src/tools/marketplaces/registrations.ts): Integration registry · Connects asset-marketplace providers. · `editor/src/tools/marketplaces/registrations.ts`

### Website

Separate marketing and conversion application.

- [Website app](https://github.com/babylonjs/editor/blob/master/website/src/app/page.tsx): Next.js app · Separate marketing, docs, and downloads application. · `website/src/app/page.tsx`
- [Conversion API](https://github.com/babylonjs/editor/blob/master/website/src/app/api/converter/route.ts): Next.js route · Invokes Assimp/Blender-oriented conversion. · `website/src/app/api/converter/route.ts`

## Connections

- Editor bootstrap → Main-process events: starts
- Main-process events → Window lifecycle: manages
- Main-process events → Export IPC: registers
- Main-process events → Custom protocol: registers
- Editor bootstrap → React editor root: launches
- React editor root → Persistent editor layout: renders
- Persistent editor layout → Babylon scene preview: hosts
- Persistent editor layout → Inspector: hosts
- Persistent editor layout → Scene commands & tools: uses
- Scene commands & tools → Project export: initiates export
- Project loader → Scene reconstruction: loads
- Scene reconstruction → Mesh loading plugin: installs
- Project loader → Persistent editor layout: hydrates scene
- Scene commands & tools → Scene serialization: persists
- Scene serialization → Project export: serializes for
- Project export → Asset export: processes
- Project export → Export IPC: uses native export
- Project export → Application templates: packages into
- Application templates → Tools runtime library: depends on
- Tools runtime library → Runtime scene loader: provides
- Tools runtime library → Cinematic playback: provides
- Headless CLI → CLI pack pipeline: runs
- CLI pack pipeline → Project export: headless packaging
- MCP tool server → Editor MCP bridge: sends requests
- Editor MCP bridge → Scene commands & tools: executes actions
- Marketplace registrations → Scene commands & tools: imports assets
- Website app → Conversion API: calls