How sxjalxo/sugar-engine works
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: Scene.h Scene · SuGarApp.h SuGarApp · Renderer.h Renderer · EditorCommands.h Editor
Components 27
Application
Bootstrapping and frame orchestration
- main · Program entry that boots the app
src/main.cpp - SuGarApp · Owns the main loop and system wiring
src/SuGarApp.h - Engine State · Edit, Play, and Paused boundaries
src/core/EngineState.h
Scene Data
ECS, scene objects, and persistence
- Scene · Top-level world state and object container
src/scene/Scene.h - ECS Core · Entity and component storage backbone
src/ecs/Registry.h - Entities · Entity lifetime and lookup management
src/ecs/EntityManager.h - Components · Shared data definitions for entities
src/ecs/Components.h - Hierarchy · Parent-child object relationships and transforms
src/scene/GameObject.h - Behaviors · Named behavior registry and callbacks
src/scene/BehaviorRegistry.h - Serializer · Scene save and load pipeline
src/scene/SceneSerializer.h - Prefabs · Save, instantiate, revert, and apply subtrees
src/scene/SceneSerializer.cpp
Runtime Systems
Input, rendering, physics, audio, and assets
- Input · Raw keyboard, mouse, and device input
src/core/Input.h - Actions · Named actions and axes abstraction
src/core/InputActions.h - Renderer · Coordinates the Vulkan render pipeline
src/Renderer.h - Render Passes · Pass-based rendering structure
src/RenderPass.h - GPU Scene · Camera, mesh, material, texture, and buffers
src/rendering/Camera.h - Shaders · Forward and shadow shader stages
shaders/basic.vert - Assets · Caching, handles, registry, and hot reload
src/assets/ResourceManager.h - Importers · glTF and mesh/model loaders
src/assets/ModelImporter.h - Audio · Audio engine, system, and clip loading
src/audio/AudioEngine.h - Physics · Fixed-step collision and contact events
src/physics/PhysicsWorld.h
Editor
UI and editing actions
- Editor · ImGui-based authoring and play controls
src/editor/EditorCommands.h
Vendored Dependencies
Third-party libraries bundled in the repo
- ImGui · Vendored UI framework used by the editor
external/imgui/imgui.h - GLFW · Vendored window, context, and input backend
external/glfw/include/GLFW/glfw3.h - Vulkan · Graphics backend for rendering
- miniaudio · Vendored audio I/O backend
external/miniaudio/miniaudio.h - tinygltf · Vendored glTF parsing support
external/tinygltf/tiny_gltf.h
Connections 32
- 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