# sxjalxo/sugar-engine architecture

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

- Interactive diagram: https://gitdiagram.com/sxjalxo/sugar-engine
- Repository: https://github.com/sxjalxo/sugar-engine

## Overview

1. **Top-level shape**
   - This is a single C++17 desktop application built with CMake.
   - `src/main.cpp` boots `SuGarApp`, which owns the main loop and wires together editor, runtime, rendering, input, audio, physics, and asset systems.
   - The project is self-contained: third-party code is vendored under `external/`.

2. **Application and engine state**
   - `SuGarApp` sits above the rest of the engine and drives the frame loop.
   - `core/EngineState` defines the major mode boundary: Edit, Play, and Paused.
   - The app coordinates the mode transition logic, including scene snapshot/restore when entering and leaving Play mode.

3. **Scene and ECS layer**
   - The engine is built around an ECS in `src/ecs/`.
   - `EntityManager`, `Registry`, and component storage manage entities and component data separately.
   - Scene-level concepts live in `src/scene/`: `Scene`, `GameObject`, `Hierarchy`, `Transform`, `Light`, `Behavior`, and serialization support.
   - This layer is the central data model consumed by rendering, physics, audio, and the editor.

4. **Scene serialization and prefabs**
   - `SceneSerializer` handles persistence of the current scene to disk, with `scene.json` as the visible project-level scene file.
   - Prefab support is part of the scene pipeline: subtrees can be saved, instantiated, reverted, and applied back to source.
   - This creates a boundary between authoring data and runtime-instantiated scene objects.

5. **Editor subsystem**
   - `src/editor/` contains command types used for undo/redo and editor actions.
   - The editor is an ImGui-based layer on top of the runtime, with hierarchy, inspector, viewport, asset browser, and play controls described in the README.
   - `ImGuizmo` is used for transform gizmos, and editor interactions are routed through the ECS and scene systems rather than bypassing them.

6. **Input and control mapping**
   - `core/Input` handles raw device state, while `InputActions` maps those inputs into named actions and axes.
   - Behaviors consume action names rather than GLFW key codes directly, which isolates gameplay logic from windowing/input backend details.
   - The editor also uses the same input layer for camera control, selection, and shortcuts.

7. **Rendering pipeline**
   - `Renderer` is the rendering hub.
   - `RenderPass` and `BasicTrianglePass` indicate a pass-based Vulkan renderer with explicit stage separation.
   - `rendering/` holds the GPU-facing scene data types: `Camera`, `Mesh`, `Material`, `Texture`, `Vertex`, and `UniformBufferObject`.
   - Shaders live in `shaders/` and are split into at least basic forward shading and shadow map passes.

8. **Render output and editor viewport**
   - The renderer supports offscreen rendering so the editor viewport can display the game view inside ImGui.
   - The viewport is also the basis for scene picking and gizmo interaction.
   - This means rendering is both a runtime output and an editor data source.

9. **Asset pipeline and resource management**
   - `src/assets/` contains the resource system: `ResourceManager`, `AssetRegistry`, `FileWatcher`, loaders, and handle types.
   - Assets are handle-based, cached, and hot-reloadable; GPU lifetime management is part of this layer.
   - Importers include mesh/model paths through `ModelImporter`, `ModelLoader`, `GltfLoader`, and glTF-specific structures.
   - Texture loading uses `stb_image`, while glTF parsing uses `tinygltf`.

10. **Model and texture ingestion flow**
    - `.obj`, `.gltf/.glb`, and image assets are brought in through the asset pipeline and converted into engine resources.
    - glTF import maps node hierarchies into ECS entities and preserves transform hierarchy and material factors.
    - Assets under `assets/models`, `assets/textures`, and `assets/audio` are part of the repo’s runtime content set.

11. **Physics and collision events**
    - `src/physics/PhysicsWorld` implements the hand-rolled physics simulation.
    - `PhysicsComponents` and `CollisionEvent` define the data and event boundary.
    - Each fixed update step resolves collisions and emits contact events that can be consumed by behaviors.
    - Physics is integrated into gameplay update, not into the render frame loop.

12. **Behavior and gameplay scripting**
    - `src/scene/Behavior` and `BehaviorRegistry` define the engine’s behavior model.
    - Behaviors are name-registered and stateless at the type level; per-entity state stays in components.
    - The runtime calls behavior hooks such as start, update, and collision response during the fixed timestep.

13. **Audio subsystem**
    - `src/audio/AudioEngine`, `AudioSystem`, `AudioLoader`, and `AudioClip` form a separate runtime subsystem.
    - `miniaudio` is used as the thin device/backend layer, while mixing and resampling are engine-owned.
    - Audio sources and listener components are part of the ECS, and collision events can trigger sounds.
    - Audio pause/stop behavior follows the engine state machine rather than running independently.

14. **External dependency boundary**
    - Core external libraries are GLFW for window/context/input, Vulkan for graphics, ImGui for editor UI, ImGuizmo for transform manipulation, miniaudio for audio I/O, stb_image for image loading, tinygltf for glTF parsing, and GLM for math.
    - These are vendored in `external/`, so the repo builds as a closed source tree with no network-time dependency resolution.

15. **Architectural data flow**
    - The dominant flow is: input and file changes enter through the app; the ECS/scene graph is mutated by editor, gameplay, physics, and loaders; the renderer and audio system consume ECS state; serialization and asset management persist and reload content.
    - The most important boundaries for a diagram are: application mode, ECS/scene data, rendering, asset/resource management, physics, audio, and editor UI.

Main entry points: [`src/scene/Scene.h`](https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/Scene.h) (Scene), [`src/SuGarApp.h`](https://github.com/sxjalxo/sugar-engine/blob/main/src/SuGarApp.h) (SuGarApp), [`src/Renderer.h`](https://github.com/sxjalxo/sugar-engine/blob/main/src/Renderer.h) (Renderer), [`src/editor/EditorCommands.h`](https://github.com/sxjalxo/sugar-engine/blob/main/src/editor/EditorCommands.h) (Editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["Application"]
  node_node_main["main<br/>entrypoint<br/>[main.cpp]"]
  node_node_app["SuGarApp<br/>app shell<br/>[SuGarApp.h]"]
  node_node_state{{"Engine State<br/>mode model<br/>[EngineState.h]"}}
end

subgraph group_group_data["Scene Data"]
  node_node_scene["Scene<br/>[Scene.h]"]
  node_node_ecs["ECS Core<br/>entity component system<br/>[Registry.h]"]
  node_node_entities["Entities<br/>entity manager<br/>[EntityManager.h]"]
  node_node_components["Components<br/>component storage<br/>[Components.h]"]
  node_node_hierarchy["Hierarchy<br/>scene graph<br/>[GameObject.h]"]
  node_node_behavior["Behaviors<br/>gameplay hooks<br/>[BehaviorRegistry.h]"]
  node_node_serialize["Serializer<br/>scene persistence<br/>[SceneSerializer.h]"]
  node_node_prefab["Prefabs<br/>scene instancing"]
end

subgraph group_group_runtime["Runtime Systems"]
  node_node_input["Input<br/>device state<br/>[Input.h]"]
  node_node_actions["Actions<br/>input mapping<br/>[InputActions.h]"]
  node_node_renderer["Renderer<br/>render hub<br/>[Renderer.h]"]
  node_node_pass["Render Passes<br/>pipeline stages<br/>[RenderPass.h]"]
  node_node_gpu["GPU Scene<br/>render data<br/>[Camera.h]"]
  node_node_shaders["Shaders<br/>gpu programs<br/>[basic.vert]"]
  node_node_assets["Assets<br/>resource system<br/>[ResourceManager.h]"]
  node_node_import["Importers<br/>model ingestion<br/>[ModelImporter.h]"]
  node_node_audio["Audio<br/>runtime subsystem<br/>[AudioEngine.h]"]
  node_node_physics["Physics<br/>simulation<br/>[PhysicsWorld.h]"]
end

subgraph group_group_editor["Editor"]
  node_node_editor["Editor<br/>ui layer<br/>[EditorCommands.h]"]
end

subgraph group_group_external["Vendored Dependencies"]
  node_node_imgui["ImGui<br/>ui library<br/>[imgui.h]"]
  node_node_glfw["GLFW<br/>window/input library<br/>[glfw3.h]"]
  node_node_vulkan["Vulkan<br/>graphics api"]
  node_node_miniaudio["miniaudio<br/>audio backend<br/>[miniaudio.h]"]
  node_node_tinygltf["tinygltf<br/>gltf parser<br/>[tiny_gltf.h]"]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"tracks"| node_node_state
node_node_app -->|"polls"| node_node_input
node_node_app -->|"hosts"| node_node_editor
node_node_app -->|"drives"| node_node_scene
node_node_app -->|"updates"| node_node_renderer
node_node_app -->|"steps"| node_node_physics
node_node_app -->|"ticks"| node_node_audio
node_node_scene -->|"uses"| node_node_ecs
node_node_ecs -->|"contains"| node_node_entities
node_node_ecs -->|"stores"| node_node_components
node_node_scene -->|"organizes"| node_node_hierarchy
node_node_scene -->|"runs"| node_node_behavior
node_node_scene -->|"persists"| node_node_serialize
node_node_scene -->|"instantiates"| node_node_prefab
node_node_editor -->|"edits"| node_node_scene
node_node_editor -->|"uses"| node_node_input
node_node_editor -->|"views"| node_node_renderer
node_node_renderer -->|"executes"| node_node_pass
node_node_renderer -->|"consumes"| node_node_gpu
node_node_renderer -->|"binds"| node_node_shaders
node_node_assets -->|"loads"| node_node_import
node_node_assets -->|"feeds"| node_node_scene
node_node_audio -->|"loads"| node_node_assets
node_node_physics -->|"simulates"| node_node_scene
node_node_behavior -->|"responds"| node_node_physics
node_node_behavior -->|"triggers"| node_node_audio
node_node_input -->|"backed by"| node_node_glfw
node_node_renderer -->|"uses"| node_node_vulkan
node_node_editor -->|"built on"| node_node_imgui
node_node_audio -->|"backed by"| node_node_miniaudio
node_node_import -->|"parses"| node_node_tinygltf

click node_node_main "https://github.com/sxjalxo/sugar-engine/blob/main/src/main.cpp"
click node_node_app "https://github.com/sxjalxo/sugar-engine/blob/main/src/SuGarApp.h"
click node_node_state "https://github.com/sxjalxo/sugar-engine/blob/main/src/core/EngineState.h"
click node_node_scene "https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/Scene.h"
click node_node_ecs "https://github.com/sxjalxo/sugar-engine/blob/main/src/ecs/Registry.h"
click node_node_entities "https://github.com/sxjalxo/sugar-engine/blob/main/src/ecs/EntityManager.h"
click node_node_components "https://github.com/sxjalxo/sugar-engine/blob/main/src/ecs/Components.h"
click node_node_hierarchy "https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/GameObject.h"
click node_node_behavior "https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/BehaviorRegistry.h"
click node_node_serialize "https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/SceneSerializer.h"
click node_node_prefab "https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/SceneSerializer.cpp"
click node_node_input "https://github.com/sxjalxo/sugar-engine/blob/main/src/core/Input.h"
click node_node_actions "https://github.com/sxjalxo/sugar-engine/blob/main/src/core/InputActions.h"
click node_node_renderer "https://github.com/sxjalxo/sugar-engine/blob/main/src/Renderer.h"
click node_node_pass "https://github.com/sxjalxo/sugar-engine/blob/main/src/RenderPass.h"
click node_node_gpu "https://github.com/sxjalxo/sugar-engine/blob/main/src/rendering/Camera.h"
click node_node_shaders "https://github.com/sxjalxo/sugar-engine/blob/main/shaders/basic.vert"
click node_node_assets "https://github.com/sxjalxo/sugar-engine/blob/main/src/assets/ResourceManager.h"
click node_node_import "https://github.com/sxjalxo/sugar-engine/blob/main/src/assets/ModelImporter.h"
click node_node_audio "https://github.com/sxjalxo/sugar-engine/blob/main/src/audio/AudioEngine.h"
click node_node_physics "https://github.com/sxjalxo/sugar-engine/blob/main/src/physics/PhysicsWorld.h"
click node_node_editor "https://github.com/sxjalxo/sugar-engine/blob/main/src/editor/EditorCommands.h"
click node_node_imgui "https://github.com/sxjalxo/sugar-engine/blob/main/external/imgui/imgui.h"
click node_node_glfw "https://github.com/sxjalxo/sugar-engine/blob/main/external/glfw/include/GLFW/glfw3.h"
click node_node_miniaudio "https://github.com/sxjalxo/sugar-engine/blob/main/external/miniaudio/miniaudio.h"
click node_node_tinygltf "https://github.com/sxjalxo/sugar-engine/blob/main/external/tinygltf/tiny_gltf.h"

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_node_main,node_node_app,node_node_state toneBlue
class node_node_scene,node_node_ecs,node_node_entities,node_node_components,node_node_hierarchy,node_node_behavior,node_node_serialize,node_node_prefab toneAmber
class node_node_input,node_node_actions,node_node_renderer,node_node_pass,node_node_gpu,node_node_shaders,node_node_assets,node_node_import,node_node_audio,node_node_physics toneMint
class node_node_editor toneRose
class node_node_imgui,node_node_glfw,node_node_vulkan,node_node_miniaudio,node_node_tinygltf toneIndigo
```

## Components

### Application

Bootstrapping and frame orchestration

- [main](https://github.com/sxjalxo/sugar-engine/blob/main/src/main.cpp): entrypoint · Program entry that boots the app · `src/main.cpp`
- [SuGarApp](https://github.com/sxjalxo/sugar-engine/blob/main/src/SuGarApp.h): app shell · Owns the main loop and system wiring · `src/SuGarApp.h`
- [Engine State](https://github.com/sxjalxo/sugar-engine/blob/main/src/core/EngineState.h): mode model · Edit, Play, and Paused boundaries · `src/core/EngineState.h`

### Scene Data

ECS, scene objects, and persistence

- [Scene](https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/Scene.h): scene model · Top-level world state and object container · `src/scene/Scene.h`
- [ECS Core](https://github.com/sxjalxo/sugar-engine/blob/main/src/ecs/Registry.h): entity component system · Entity and component storage backbone · `src/ecs/Registry.h`
- [Entities](https://github.com/sxjalxo/sugar-engine/blob/main/src/ecs/EntityManager.h): entity manager · Entity lifetime and lookup management · `src/ecs/EntityManager.h`
- [Components](https://github.com/sxjalxo/sugar-engine/blob/main/src/ecs/Components.h): component storage · Shared data definitions for entities · `src/ecs/Components.h`
- [Hierarchy](https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/GameObject.h): scene graph · Parent-child object relationships and transforms · `src/scene/GameObject.h`
- [Behaviors](https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/BehaviorRegistry.h): gameplay hooks · Named behavior registry and callbacks · `src/scene/BehaviorRegistry.h`
- [Serializer](https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/SceneSerializer.h): scene persistence · Scene save and load pipeline · `src/scene/SceneSerializer.h`
- [Prefabs](https://github.com/sxjalxo/sugar-engine/blob/main/src/scene/SceneSerializer.cpp): scene instancing · Save, instantiate, revert, and apply subtrees · `src/scene/SceneSerializer.cpp`

### Runtime Systems

Input, rendering, physics, audio, and assets

- [Input](https://github.com/sxjalxo/sugar-engine/blob/main/src/core/Input.h): device state · Raw keyboard, mouse, and device input · `src/core/Input.h`
- [Actions](https://github.com/sxjalxo/sugar-engine/blob/main/src/core/InputActions.h): input mapping · Named actions and axes abstraction · `src/core/InputActions.h`
- [Renderer](https://github.com/sxjalxo/sugar-engine/blob/main/src/Renderer.h): render hub · Coordinates the Vulkan render pipeline · `src/Renderer.h`
- [Render Passes](https://github.com/sxjalxo/sugar-engine/blob/main/src/RenderPass.h): pipeline stages · Pass-based rendering structure · `src/RenderPass.h`
- [GPU Scene](https://github.com/sxjalxo/sugar-engine/blob/main/src/rendering/Camera.h): render data · Camera, mesh, material, texture, and buffers · `src/rendering/Camera.h`
- [Shaders](https://github.com/sxjalxo/sugar-engine/blob/main/shaders/basic.vert): gpu programs · Forward and shadow shader stages · `shaders/basic.vert`
- [Assets](https://github.com/sxjalxo/sugar-engine/blob/main/src/assets/ResourceManager.h): resource system · Caching, handles, registry, and hot reload · `src/assets/ResourceManager.h`
- [Importers](https://github.com/sxjalxo/sugar-engine/blob/main/src/assets/ModelImporter.h): model ingestion · glTF and mesh/model loaders · `src/assets/ModelImporter.h`
- [Audio](https://github.com/sxjalxo/sugar-engine/blob/main/src/audio/AudioEngine.h): runtime subsystem · Audio engine, system, and clip loading · `src/audio/AudioEngine.h`
- [Physics](https://github.com/sxjalxo/sugar-engine/blob/main/src/physics/PhysicsWorld.h): simulation · Fixed-step collision and contact events · `src/physics/PhysicsWorld.h`

### Editor

UI and editing actions

- [Editor](https://github.com/sxjalxo/sugar-engine/blob/main/src/editor/EditorCommands.h): ui layer · ImGui-based authoring and play controls · `src/editor/EditorCommands.h`

### Vendored Dependencies

Third-party libraries bundled in the repo

- [ImGui](https://github.com/sxjalxo/sugar-engine/blob/main/external/imgui/imgui.h): ui library · Vendored UI framework used by the editor · `external/imgui/imgui.h`
- [GLFW](https://github.com/sxjalxo/sugar-engine/blob/main/external/glfw/include/GLFW/glfw3.h): window/input library · Vendored window, context, and input backend · `external/glfw/include/GLFW/glfw3.h`
- **Vulkan**: graphics api · Graphics backend for rendering
- [miniaudio](https://github.com/sxjalxo/sugar-engine/blob/main/external/miniaudio/miniaudio.h): audio backend · Vendored audio I/O backend · `external/miniaudio/miniaudio.h`
- [tinygltf](https://github.com/sxjalxo/sugar-engine/blob/main/external/tinygltf/tiny_gltf.h): gltf parser · Vendored glTF parsing support · `external/tinygltf/tiny_gltf.h`

## Connections

- main → SuGarApp: boots · Entry point creates the application shell
- SuGarApp → Engine State: tracks · App manages edit/play/pause transitions
- SuGarApp → Input: polls · Frame loop reads device input
- SuGarApp → Editor: hosts · Editor runs as an overlay layer
- SuGarApp → Scene: drives · App owns the active scene lifecycle
- SuGarApp → Renderer: updates · App advances rendering each frame
- SuGarApp → Physics: steps · App advances fixed simulation
- SuGarApp → Audio: ticks · App coordinates audio with engine state
- Scene → ECS Core: uses · Scene state is built on ECS storage
- ECS Core → Entities: contains · Entity manager owns entity identities
- ECS Core → Components: stores · Component storage holds per-entity data
- Scene → Hierarchy: organizes · Game objects form the hierarchy
- Scene → Behaviors: runs · Scene invokes registered behaviors
- Scene → Serializer: persists · Scene serializer saves and loads scenes
- Scene → Prefabs: instantiates · Prefab flow creates reusable scene subtrees
- Editor → Scene: edits · Editor mutates scene and ECS data
- Editor → Input: uses · Editor shortcuts and camera control share input
- Editor → Renderer: views · Viewport consumes offscreen renders
- Renderer → Render Passes: executes · Renderer schedules render passes
- Renderer → GPU Scene: consumes · Renderer reads GPU-facing scene resources
- Renderer → Shaders: binds · Renderer uses shader stages
- Assets → Importers: loads · Resource system routes model and texture ingestion
- Assets → Scene: feeds · Loaded assets populate scene objects
- Audio → Assets: loads · Audio clips are managed as resources
- Physics → Scene: simulates · Physics reads and mutates scene components
- Behaviors → Physics: responds · Behaviors can consume collision events
- Behaviors → Audio: triggers · Behaviors may trigger audio responses
- Input → GLFW: backed by · Windowing backend provides raw device events
- Renderer → Vulkan: uses · Graphics implementation targets Vulkan
- Editor → ImGui: built on · Editor UI is implemented with ImGui
- Audio → miniaudio: backed by · Audio I/O uses miniaudio
- Importers → tinygltf: parses · glTF importer relies on tinygltf
