# dsbch/engine architecture

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

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

## Overview

1. **Repository shape**
   - This is a C++ engine repo split into three runnable layers: `engine` (shared runtime), `sandbox` (testbed/demo app), and `editor` (tooling app).
   - Build orchestration is done with Premake (`premake5.lua` plus per-project Lua scripts), and the solution file is `dsengine.slnx`.

2. **Top-level runtime model**
   - The engine is organized around an application loop that owns global state, a window, and a renderer.
   - Higher-level app code lives in `sandbox` and `editor`, while reusable engine code lives under `engine/src`.

3. **Core engine foundation**
   - `engine/src/base` contains cross-cutting utilities: logging, errors, config, timers, hashing, context, cache, and a ring buffer for concurrency.
   - These pieces support initialization, diagnostics, and shared runtime services without being tied to rendering or gameplay.

4. **Scene and ECS-like structure**
   - `engine/src/core/scene` defines entities, components, scenes, and systems.
   - Systems are split by responsibility: animation, camera, and render, which suggests a data-oriented scene update pipeline.

5. **Event and camera flow**
   - `engine/src/core/events` provides event types and dispatching.
   - Camera control is separated into its own component/system pair, so input-driven view updates are isolated from rendering and scene ownership.

6. **Asset and content processing**
   - `engine/src/core/amanager` contains asset/material/meshlet/primitive processors, indicating an offline or runtime asset preparation layer.
   - The presence of `meshletProcessor` and `primitiveProcessor` suggests geometry is transformed into renderer-friendly structures before drawing.

7. **Rendering abstraction boundary**
   - `engine/src/platform/renderer` is the renderer interface layer, with shared types like `shader`, `texture`, and `vertex`.
   - This layer isolates the engine from a specific graphics API while exposing the API-neutral rendering contract.

8. **Vulkan backend**
   - `engine/src/platform/renderer/vulkan` is the concrete backend and contains the full GPU implementation: buffers, images, descriptors, pipelines, swapchain, submission, shader loading, registry, and deletion queue.
   - Specialized renderers exist for meshlets, lines, compute, and UI, showing that the backend is split by rendering mode rather than being a single monolith.

9. **Modern rendering features**
   - The shader set in `assets/shaders` includes mesh, compute culling, hierarchical Z-buffer, line, composite, and accumulation shaders.
   - This points to a GPU-driven pipeline with compute-assisted visibility/acceleration stages and meshlet-based rendering.

10. **Asset and shader pipeline**
    - Shader sources are in HLSL and precompiled SPIR-V binaries are stored under `assets/shaders/vkCompiled`.
    - The repo treats compiled shaders as part of the runtime asset set, which means shader compilation is an explicit step in the content pipeline.

11. **Application layers**
    - `sandbox` is the interactive demo/runtime app; its README hints at keyboard-driven model loading and instance manipulation.
    - `editor` is a separate tooling app, likely intended for scene/content authoring on top of the same engine runtime.

12. **Platform and windowing**
    - `engine/src/platform/window` handles window creation and OS-facing lifecycle.
    - The renderer and window boundaries are separate, so rendering can be swapped or reworked without changing the rest of the engine.

13. **External dependencies and tooling**
    - Vulkan is the primary graphics API, and the README explicitly requires the LunarG Vulkan SDK.
    - `vendor` and the submodule file indicate third-party dependencies are integrated locally rather than fetched dynamically at runtime.

14. **Likely end-to-end data flow**
    - Application starts → engine initializes config/logger/context/window → scene is loaded → systems update camera/animation → render system hands visible data to the Vulkan backend → backend records/submits GPU work → swapchain presents the frame.
    - Asset processing and shader compilation sit on the path before rendering, while the sandbox/editor are the main entry points for exercising that pipeline.

Main entry points: [`engine/src/application/application.cpp`](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/application/application.cpp) (App loop), [`engine/src/core/scene/scene.cpp`](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/scene/scene.cpp) (Scene model), [`premake5.lua`](https://github.com/dsbch/engine/blob/engine-vulkan/premake5.lua) (Premake), [`engine/src/core/scene/systems/render/renderSystem.cpp`](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/scene/systems/render/renderSystem.cpp) (Render system)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build"]
  node_solution["Solution<br/>build entry<br/>[dsengine.slnx]"]
  node_premake["Premake<br/>build script<br/>[premake5.lua]"]
  node_engine_lua["Engine Lua<br/>project script<br/>[engine.lua]"]
  node_editor_lua["Editor Lua<br/>project script<br/>[editor.lua]"]
end

subgraph group_apps["Apps"]
  node_sandbox_app["Sandbox<br/>demo app<br/>[main.cpp]"]
  node_editor_app["Editor<br/>tooling app<br/>[editor.cpp]"]
end

subgraph group_engine["Engine"]
  node_app_loop["App loop<br/>runtime core<br/>[application.cpp]"]
  node_base_rt["Base runtime<br/>foundation<br/>[logger.cpp]"]
  node_scene_model["Scene model<br/>ecs scene<br/>[scene.cpp]"]
  node_event_bus["Events<br/>event dispatch<br/>[dispatcher.cpp]"]
  node_camera_core["Camera<br/>view control<br/>[camera.cpp]"]
  node_asset_mgr["Assets<br/>content pipeline<br/>[aManager.cpp]"]
  node_anim_sys["Animation<br/>scene system<br/>[animation.cpp]"]
  node_cam_sys["Camera system<br/>scene system<br/>[cameraSystem.cpp]"]
  node_render_sys["Render system<br/>scene system<br/>[renderSystem.cpp]"]
  node_window["Window<br/>[window.cpp]"]
end

subgraph group_render["Rendering"]
  node_renderer_if["Renderer API<br/>render interface<br/>[renderer.cpp]"]
  node_vk_backend["Vulkan backend<br/>gpu backend<br/>[renderer.cpp]"]
end

subgraph group_content["Content"]
  node_shaders["Shaders<br/>gpu assets<br/>[vkMesh.hlsl]"]
end

node_solution -->|"builds via"| node_premake
node_premake -->|"includes"| node_engine_lua
node_premake -->|"includes"| node_editor_lua
node_app_loop -->|"uses"| node_base_rt
node_app_loop -->|"owns"| node_window
node_app_loop -->|"drives"| node_renderer_if
node_scene_model -->|"publishes"| node_event_bus
node_scene_model -->|"runs"| node_anim_sys
node_scene_model -->|"runs"| node_cam_sys
node_scene_model -->|"runs"| node_render_sys
node_cam_sys -->|"updates"| node_camera_core
node_render_sys -->|"consumes"| node_asset_mgr
node_render_sys -->|"targets"| node_renderer_if
node_renderer_if -->|"implemented by"| node_vk_backend
node_vk_backend -->|"presents via"| node_window
node_vk_backend -->|"loads"| node_shaders
node_sandbox_app -->|"uses"| node_app_loop
node_editor_app -->|"uses"| node_app_loop
node_asset_mgr -->|"aligns with"| node_shaders

click node_solution "https://github.com/dsbch/engine/blob/engine-vulkan/dsengine.slnx"
click node_premake "https://github.com/dsbch/engine/blob/engine-vulkan/premake5.lua"
click node_engine_lua "https://github.com/dsbch/engine/blob/engine-vulkan/engine/engine.lua"
click node_editor_lua "https://github.com/dsbch/engine/blob/engine-vulkan/editor/editor.lua"
click node_app_loop "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/application/application.cpp"
click node_base_rt "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/base/logger/logger.cpp"
click node_scene_model "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/scene/scene.cpp"
click node_event_bus "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/events/dispatcher.cpp"
click node_camera_core "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/camera/camera.cpp"
click node_asset_mgr "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/amanager/aManager.cpp"
click node_anim_sys "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/scene/systems/animation/animation.cpp"
click node_cam_sys "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/scene/systems/camera/cameraSystem.cpp"
click node_render_sys "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/scene/systems/render/renderSystem.cpp"
click node_window "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/platform/window/window.cpp"
click node_renderer_if "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/platform/renderer/renderer.cpp"
click node_vk_backend "https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/platform/renderer/vulkan/renderer.cpp"
click node_sandbox_app "https://github.com/dsbch/engine/blob/engine-vulkan/sandbox/src/main.cpp"
click node_editor_app "https://github.com/dsbch/engine/blob/engine-vulkan/editor/src/editor.cpp"
click node_shaders "https://github.com/dsbch/engine/blob/engine-vulkan/assets/shaders/vkMesh.hlsl"

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_solution,node_premake,node_engine_lua,node_editor_lua toneBlue
class node_sandbox_app,node_editor_app toneAmber
class node_app_loop,node_base_rt,node_scene_model,node_event_bus,node_camera_core,node_asset_mgr,node_anim_sys,node_cam_sys,node_render_sys,node_window toneMint
class node_renderer_if,node_vk_backend toneRose
class node_shaders toneIndigo
```

## Components

### Build

Solution and project orchestration

- [Solution](https://github.com/dsbch/engine/blob/engine-vulkan/dsengine.slnx): build entry · Top-level Visual Studio solution · `dsengine.slnx`
- [Premake](https://github.com/dsbch/engine/blob/engine-vulkan/premake5.lua): build script · Root build orchestration · `premake5.lua`
- [Engine Lua](https://github.com/dsbch/engine/blob/engine-vulkan/engine/engine.lua): project script · Engine project definition · `engine/engine.lua`
- [Editor Lua](https://github.com/dsbch/engine/blob/engine-vulkan/editor/editor.lua): project script · Editor project definition · `editor/editor.lua`

### Apps

Runnable entry points

- [Sandbox](https://github.com/dsbch/engine/blob/engine-vulkan/sandbox/src/main.cpp): demo app · Interactive runtime and model-loading testbed · `sandbox/src/main.cpp`
- [Editor](https://github.com/dsbch/engine/blob/engine-vulkan/editor/src/editor.cpp): tooling app · Authoring/tooling application on top of the engine · `editor/src/editor.cpp`

### Engine

Reusable runtime and systems

- [App loop](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/application/application.cpp): runtime core · Owns lifecycle and global execution state · `engine/src/application/application.cpp`
- [Base runtime](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/base/logger/logger.cpp): foundation · Logging, config, context, timing, errors, hashing, cache, concurrency · `engine/src/base/logger/logger.cpp`
- [Scene model](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/scene/scene.cpp): ecs scene · Entities, components, scenes, and system contracts · `engine/src/core/scene/scene.cpp`
- [Events](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/events/dispatcher.cpp): event dispatch · Event types and dispatcher for runtime coordination · `engine/src/core/events/dispatcher.cpp`
- [Camera](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/camera/camera.cpp): view control · Camera state and control logic · `engine/src/core/camera/camera.cpp`
- [Assets](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/amanager/aManager.cpp): content pipeline · Asset, material, meshlet, and primitive processing · `engine/src/core/amanager/aManager.cpp`
- [Animation](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/scene/systems/animation/animation.cpp): scene system · Scene animation update system · `engine/src/core/scene/systems/animation/animation.cpp`
- [Camera system](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/scene/systems/camera/cameraSystem.cpp): scene system · Scene system that updates camera behavior · `engine/src/core/scene/systems/camera/cameraSystem.cpp`
- [Render system](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/core/scene/systems/render/renderSystem.cpp): scene system · Scene-to-renderer bridge · `engine/src/core/scene/systems/render/renderSystem.cpp`
- [Window](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/platform/window/window.cpp): platform window · OS window creation and lifecycle · `engine/src/platform/window/window.cpp`

### Rendering

API-neutral interface and Vulkan backend

- [Renderer API](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/platform/renderer/renderer.cpp): render interface · API-neutral renderer contract and shared types · `engine/src/platform/renderer/renderer.cpp`
- [Vulkan backend](https://github.com/dsbch/engine/blob/engine-vulkan/engine/src/platform/renderer/vulkan/renderer.cpp): gpu backend · Concrete Vulkan renderer implementation · `engine/src/platform/renderer/vulkan/renderer.cpp`

### Content

Assets and shader pipeline

- [Shaders](https://github.com/dsbch/engine/blob/engine-vulkan/assets/shaders/vkMesh.hlsl): gpu assets · HLSL sources and compiled SPIR-V shader set · `assets/shaders/vkMesh.hlsl`

## Connections

- Solution → Premake: builds via · Solution is generated and coordinated through Premake
- Premake → Engine Lua: includes · Root build pulls in engine project definition
- Premake → Editor Lua: includes · Root build pulls in editor project definition
- App loop → Base runtime: uses · Application loop depends on shared runtime services
- App loop → Window: owns · Application lifecycle manages the OS window
- App loop → Renderer API: drives · Application initializes and coordinates rendering
- Scene model → Events: publishes · Scene logic is coordinated through events
- Scene model → Animation: runs · Animation is a scene system
- Scene model → Camera system: runs · Camera updates are part of scene processing
- Scene model → Render system: runs · Rendering is orchestrated from the scene layer
- Camera system → Camera: updates · Camera system manipulates camera state
- Render system → Assets: consumes · Render path uses prepared assets and geometry data
- Render system → Renderer API: targets · Scene rendering emits API-neutral draw work
- Renderer API → Vulkan backend: implemented by · Vulkan backend satisfies the rendering contract
- Vulkan backend → Window: presents via · Swapchain and frame presentation are tied to the window
- Vulkan backend → Shaders: loads · Backend consumes compiled shader assets
- Sandbox → App loop: uses · Sandbox is an entry point into the engine runtime
- Editor → App loop: uses · Editor is another entry point into the engine runtime
- Assets → Shaders: aligns with · Asset pipeline feeds rendering-oriented content