# boz0o0/ampersand-engine architecture

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

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

## Overview

Ampersand is a modular C++20 game engine with a sparse-set ECS, plus an optional desktop editor for game-folder JSON. A game configures its folder and asks SceneManager to load configuration and scenes; the engine’s modules provide ECS, input, physics, rendering, audio, networking, and scripting capabilities. The editor opens a project, presents its files and scene/entity/resource data for editing, then saves dirty documents. Dashed links mark likely runtime integration whose call sites were not shown; sampled excerpts do not establish a complete engine frame loop.

Main entry points: [`engine/src/core/ecs/Scheduler.cpp`](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/core/ecs/Scheduler.cpp) (System scheduler), [`editor/src/Panels.cpp`](https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Panels.cpp) (Editor panels), [`engine/src/scene/resources/SceneManager.cpp`](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/scene/resources/SceneManager.cpp) (Scene manager), [`editor/src/main.cpp`](https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/main.cpp) (Editor app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Project Editor"]
  node_editor_app["Editor app<br/>[main.cpp]"]
  node_editor_ui["Editor UI<br/>[Editor.cpp]"]
  node_panels["Editor panels<br/>[Panels.cpp]"]
  node_json_widgets["JSON widgets<br/>[Widgets.cpp]"]
  node_project["Project documents<br/>[Project.cpp]"]
  node_type_table["Editor types<br/>[Types.cpp]"]
end

subgraph group_scene["Scene Authoring"]
  node_game_folder["Game folder"]
  node_scene_manager["Scene manager<br/>[SceneManager.cpp]"]
  node_scene_serializers["Scene serializers<br/>[Serializers.hpp]"]
  node_scene_loaders["Resource loaders"]
end

subgraph group_core["Engine Core"]
  node_world[("ECS world<br/>[World.cpp]")]
  node_scheduler["System scheduler<br/>[Scheduler.cpp]"]
end

subgraph group_gameplay["Gameplay Modules"]
  node_input["Input manager<br/>[InputManager.cpp]"]
  node_physics["Physics systems"]
  node_render_system["Render systems<br/>[RenderSystem.cpp]"]
  node_animation["Animation system"]
  node_audio_system["Audio system<br/>[AudioSystem.cpp]"]
  node_scripting["Scripting system"]
end

subgraph group_io["Platform I/O"]
  node_network["UDP networking<br/>[UdpSocket.cpp]"]
  node_renderer["SFML renderer<br/>[SfmlRenderer.cpp]"]
  node_audio_backend["SFML audio"]
end

node_developer(("Game developer"))

node_developer -->|"opens editor"| node_editor_app
node_editor_app -->|"runs"| node_editor_ui
node_editor_ui -.->|"draws panels"| node_panels
node_panels -->|"edits documents"| node_project
node_panels -.->|"uses widgets"| node_json_widgets
node_panels -->|"gets type data"| node_type_table
node_project -->|"reads and saves"| node_game_folder
node_developer -->|"provides game data"| node_game_folder
node_game_folder -->|"loads config"| node_scene_manager
node_scene_manager -->|"creates entities"| node_world
node_scene_manager -->|"uses serialization"| node_scene_serializers
node_scene_manager -->|"registers builtins"| node_scene_loaders
node_world -.->|"runs systems"| node_scheduler
node_scheduler -.->|"dispatches system"| node_input
node_scheduler -.->|"dispatches system"| node_physics
node_scheduler -.->|"dispatches system"| node_render_system
node_scheduler -.->|"dispatches system"| node_animation
node_scheduler -.->|"dispatches system"| node_audio_system
node_scheduler -.->|"dispatches system"| node_scripting
node_render_system -.->|"renders through"| node_renderer
node_audio_system -.->|"plays through"| node_audio_backend
node_developer -.->|"uses optional module"| node_network
node_developer -->|"uses module"| node_input
node_developer -->|"uses module"| node_physics
node_developer -->|"uses module"| node_renderer
node_developer -->|"uses module"| node_audio_backend
node_developer -->|"uses optional module"| node_scripting

click node_editor_app "https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/main.cpp"
click node_editor_ui "https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Editor.cpp"
click node_panels "https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Panels.cpp"
click node_json_widgets "https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Widgets.cpp"
click node_project "https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Project.cpp"
click node_type_table "https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Types.cpp"
click node_scene_manager "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/scene/resources/SceneManager.cpp"
click node_scene_serializers "https://github.com/boz0o0/ampersand-engine/blob/main/engine/include/ampersand/scene/serialization/Serializers.hpp"
click node_scene_loaders "https://github.com/boz0o0/ampersand-engine/tree/main/engine/src/scene/loaders"
click node_world "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/core/ecs/World.cpp"
click node_scheduler "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/core/ecs/Scheduler.cpp"
click node_input "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/input/resources/InputManager.cpp"
click node_physics "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/physics/systems/CollisionSystem.cpp"
click node_render_system "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/render/systems/RenderSystem.cpp"
click node_animation "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/render/systems/AnimationSystem.cpp"
click node_audio_system "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/audio/systems/AudioSystem.cpp"
click node_scripting "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/scripting/systems/ScriptingSystem.cpp"
click node_network "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/net/UdpSocket.cpp"
click node_renderer "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/render/SfmlRenderer.cpp"
click node_audio_backend "https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/audio/SfmlAudioEngine.cpp"

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_editor_app,node_editor_ui,node_panels,node_json_widgets,node_project,node_type_table toneBlue
class node_game_folder,node_scene_manager,node_scene_serializers,node_scene_loaders toneAmber
class node_world,node_scheduler toneMint
class node_input,node_physics,node_render_system,node_animation,node_audio_system,node_scripting toneRose
class node_network,node_renderer,node_audio_backend,node_developer toneIndigo
```

## Components

### Project Editor

- [Editor app](https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/main.cpp): `editor/src/main.cpp`
- [Editor UI](https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Editor.cpp): `editor/src/Editor.cpp`
- [Editor panels](https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Panels.cpp): `editor/src/Panels.cpp`
- [JSON widgets](https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Widgets.cpp): `editor/src/Widgets.cpp`
- [Project documents](https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Project.cpp): `editor/src/Project.cpp`
- [Editor types](https://github.com/boz0o0/ampersand-engine/blob/main/editor/src/Types.cpp): `editor/src/Types.cpp`

### Scene Authoring

- **Game folder**
- [Scene manager](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/scene/resources/SceneManager.cpp): `engine/src/scene/resources/SceneManager.cpp`
- [Scene serializers](https://github.com/boz0o0/ampersand-engine/blob/main/engine/include/ampersand/scene/serialization/Serializers.hpp): `engine/include/ampersand/scene/serialization/Serializers.hpp`
- [Resource loaders](https://github.com/boz0o0/ampersand-engine/tree/main/engine/src/scene/loaders): `engine/src/scene/loaders`

### Engine Core

- [ECS world](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/core/ecs/World.cpp): `engine/src/core/ecs/World.cpp`
- [System scheduler](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/core/ecs/Scheduler.cpp): `engine/src/core/ecs/Scheduler.cpp`

### Gameplay Modules

- [Input manager](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/input/resources/InputManager.cpp): `engine/src/input/resources/InputManager.cpp`
- [Physics systems](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/physics/systems/CollisionSystem.cpp): `engine/src/physics/systems/CollisionSystem.cpp`
- [Render systems](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/render/systems/RenderSystem.cpp): `engine/src/render/systems/RenderSystem.cpp`
- [Animation system](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/render/systems/AnimationSystem.cpp): `engine/src/render/systems/AnimationSystem.cpp`
- [Audio system](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/audio/systems/AudioSystem.cpp): `engine/src/audio/systems/AudioSystem.cpp`
- [Scripting system](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/scripting/systems/ScriptingSystem.cpp): `engine/src/scripting/systems/ScriptingSystem.cpp`

### Platform I/O

- [UDP networking](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/net/UdpSocket.cpp): `engine/src/net/UdpSocket.cpp`
- [SFML renderer](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/render/SfmlRenderer.cpp): `engine/src/render/SfmlRenderer.cpp`
- [SFML audio](https://github.com/boz0o0/ampersand-engine/blob/main/engine/src/audio/SfmlAudioEngine.cpp): `engine/src/audio/SfmlAudioEngine.cpp`

### Other components

- **Game developer**

## Connections

- Game developer → Editor app: opens editor
- Editor app → Editor UI: runs (evidence: `editor/src/main.cpp`)
- Editor UI → Editor panels: draws panels
- Editor panels → Project documents: edits documents (evidence: `editor/src/Panels.cpp`)
- Editor panels → JSON widgets: uses widgets
- Editor panels → Editor types: gets type data (evidence: `editor/src/Panels.cpp`)
- Project documents → Game folder: reads and saves
- Game developer → Game folder: provides game data
- Game folder → Scene manager: loads config
- Scene manager → ECS world: creates entities (evidence: `engine/src/scene/resources/SceneManager.cpp`)
- Scene manager → Scene serializers: uses serialization
- Scene manager → Resource loaders: registers builtins
- ECS world → System scheduler: runs systems
- System scheduler → Input manager: dispatches system
- System scheduler → Physics systems: dispatches system
- System scheduler → Render systems: dispatches system
- System scheduler → Animation system: dispatches system
- System scheduler → Audio system: dispatches system
- System scheduler → Scripting system: dispatches system
- Render systems → SFML renderer: renders through
- Audio system → SFML audio: plays through
- Game developer → UDP networking: uses optional module
- Game developer → Input manager: uses module
- Game developer → Physics systems: uses module
- Game developer → SFML renderer: uses module
- Game developer → SFML audio: uses module
- Game developer → Scripting system: uses optional module