# raikiri/legitparticles architecture

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

- Interactive diagram: https://gitdiagram.com/raikiri/legitparticles
- Repository: https://github.com/raikiri/legitparticles

## Overview

1. This repository is a desktop C++ simulation/demo application, not a generic library. The root CMake build produces an executable that runs an ECS-driven particle/cloth simulation with real-time rendering and an ImGui UI. The code is organized around a small engine layer plus a physics demo layer.

2. The top-level runtime entry point is `src/main.cpp`, which likely wires together window creation, scene setup, system registration, and the main frame loop. The application flow is typical game-engine style: poll input, advance simulation, render the scene, and draw UI each frame.

3. The core architectural boundary is the ECS in `src/ECS`. Entity data is split into:
   - `Components` for per-entity state like particles, triangles, links
   - `Context` for global/shared state such as window, input, camera, renderer, mesh/shader testbed, animation, and physics data
   - `Systems` for the actual frame-stage logic: window, input, camera, renderer, fullscreen renderer, mesh renderer, shader testbed renderer, skeletal animation, physics variants

4. Physics is a major subsystem and is split into multiple solver implementations rather than one monolithic solver. The key files are `VBDPhysics`, `SparsePhysics`, `MultigridPhysics`, `PhysicsAnimation`, and shared utilities in `PhysicsCommon` and `PhysicsGraphs`. The README makes clear the main showcased solver is AVBD/PBD-style constraint projection for particle link constraints, running CPU-side with iterative solves.

5. The physics data model is constraint-centric: particles are connected through link constraints, and scenes such as `SimpleClothScene` and `MultigridClothScene` define cloth-like setups. The `PhysicsGraphs` and solver context files suggest the solver builds and uses constraint graph information to organize iterations and dependency structure.

6. Rendering is separated from simulation through renderer systems and renderer context. `Renderer`, `MeshRenderer`, `FullscreenRenderer`, and `ShaderTestbedRenderer` suggest multiple rendering paths: general scene rendering, mesh drawing, screen-space passes, and shader experimentation. This is a typical “simulation generates transforms/positions, renderer consumes them” boundary.

7. The graphics stack is built on external libraries that materially shape the architecture: GLFW for window/context/input handling, glm for math, ImGui for runtime UI, and a local `LegitVulkan` dependency for rendering. `spirv-cross` is included for shader reflection, which implies the renderer inspects compiled shader interfaces rather than hard-coding all bindings.

8. Shader assets are first-class runtime resources. Source GLSL lives under `bin/data/Shaders/glsl`, compiled SPIR-V lives under `bin/data/Shaders/spirv`, and there are explicit build scripts for generating shader binaries. That means the runtime expects precompiled shader artifacts alongside the executable and loads them from the data directory.

9. Content/data is organized as deployable assets under `bin/data`: scenes, fonts, screenshots, animation assets, and shader binaries. JSON scene files such as `CubeScene.json` and `SponzaScene*.json` indicate scene loading is data-driven, and the `Animations/WalkTest` tree shows imported skeletal/2D animation content used by the animation system.

10. The math layer under `src/Maths` is a supporting subsystem for simulation and asset processing. It includes sparse matrix utilities, an algebraic multigrid solver, strain constraints, tensor math, rectangle packing, and a Spriter animation importer. These are not standalone features; they feed the physics solvers, animation pipeline, and resource preparation.

11. Utility code in `src/Utils` provides small shared infrastructure such as GLM include wrappers, scoped context helpers, cached arrays, and grouped argument helpers. This suggests the project favors lightweight internal helpers over a large framework.

12. Build and dependency boundaries are explicit. The repo uses CMake plus a GitHub Actions multi-platform workflow, with vendored or submodule-style third-party code under `dependencies/` including entt (ECS), GLFW, glm, imgui, jsoncpp, lodepng, tiny_obj_loader, and spirv-cross. The architecture is therefore “engine code in `src/`, third-party libraries in `dependencies/`, runtime assets in `bin/data/`.”

13. For an architecture diagram, the key data flow is: user input and window events enter via GLFW/Input -> ECS systems update camera/scene/physics -> physics writes updated particle/constraint state into components/context -> renderer systems consume that state, load shaders/assets from `bin/data`, and present frames -> ImGui overlays debug/controls on top. The main coupling points are the ECS context objects and the shared asset directory.

Main entry points: [`src/ECS/Systems/Renderer.h`](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/Renderer.h) (Renderer), [`src/main.cpp`](https://github.com/raikiri/legitparticles/blob/master/src/main.cpp) (Main), [`src/ECS/Systems/VBDPhysics.h`](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/VBDPhysics.h) (VBD Solver), [`src/ECS/Scenes/SimpleClothScene.h`](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Scenes/SimpleClothScene.h) (Cloth Scene)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["App Runtime"]
  node_n_main(("Main<br/>entrypoint<br/>[main.cpp]"))
end

subgraph group_g_ecs["ECS Layer"]
  node_n_window_sys["Window<br/>[Window.h]"]
  node_n_input_sys["Input<br/>[Input.h]"]
  node_n_camera_sys["Camera<br/>[Camera.h]"]
  node_n_phys_ctx[("Physics Data<br/>context<br/>[PhysicsData.h]")]
  node_n_particles["Particles"]
  node_n_links["Links<br/>[LinkComponent.h]"]
  node_n_triangles["Triangles"]
  node_n_cloth_scene{{"Cloth Scene<br/>[SimpleClothScene.h]"}}
  node_n_mg_scene{{"Multigrid Scene"}}
end

subgraph group_g_physics["Physics"]
  node_n_phys_anim_sys["Physics Animation<br/>[PhysicsAnimation.h]"]
  node_n_vbd_phys["VBD Solver<br/>[VBDPhysics.h]"]
  node_n_sparse_phys["Sparse Solver<br/>[SparsePhysics.h]"]
  node_n_mg_phys["Multigrid Solver<br/>[MultigridPhysics.h]"]
  node_n_phys_common["Physics Common<br/>support<br/>[PhysicsCommon.h]"]
  node_n_phys_graphs["Physics Graphs<br/>support<br/>[PhysicsGraphs.h]"]
end

subgraph group_g_render["Rendering"]
  node_n_renderer_sys["Renderer<br/>[Renderer.h]"]
  node_n_mesh_renderer_sys["Mesh Renderer<br/>[MeshRenderer.h]"]
  node_n_fs_renderer_sys["Fullscreen Pass"]
  node_n_shader_testbed_sys["Shader Testbed"]
  node_n_anim_sys["Skeletal Animation"]
  node_n_render_ctx[("Render Data<br/>context<br/>[RendererData.h]")]
  node_n_ui_ctx[("UI Data<br/>context<br/>[WindowData.h]")]
end

subgraph group_g_data["Assets"]
  node_n_shaders["Shaders<br/>assets"]
  node_n_scenes["Scenes<br/>assets"]
  node_n_animations["Animations<br/>assets"]
end

subgraph group_g_deps["Dependencies"]
  node_n_glfw["GLFW<br/>platform"]
  node_n_glm["GLM<br/>math"]
  node_n_imgui["ImGui"]
  node_n_legitvulkan["LegitVulkan<br/>render backend"]
end

node_n_main -->|"starts"| node_n_window_sys
node_n_main -->|"registers"| node_n_input_sys
node_n_main -->|"registers"| node_n_camera_sys
node_n_main -->|"selects"| node_n_vbd_phys
node_n_main -->|"drives"| node_n_renderer_sys
node_n_window_sys -->|"uses"| node_n_glfw
node_n_input_sys -->|"reads"| node_n_glfw
node_n_camera_sys -->|"updates"| node_n_render_ctx
node_n_input_sys -->|"updates"| node_n_ui_ctx
node_n_vbd_phys -->|"writes"| node_n_phys_ctx
node_n_vbd_phys -->|"mutates"| node_n_particles
node_n_vbd_phys -->|"solves"| node_n_links
node_n_vbd_phys -->|"depends on"| node_n_phys_graphs
node_n_sparse_phys -->|"shares"| node_n_phys_common
node_n_mg_phys -->|"shares"| node_n_phys_common
node_n_mg_phys -->|"depends on"| node_n_phys_graphs
node_n_phys_anim_sys -->|"reads"| node_n_phys_ctx
node_n_phys_anim_sys -->|"coordinates"| node_n_anim_sys
node_n_renderer_sys -->|"reads"| node_n_render_ctx
node_n_renderer_sys -->|"delegates"| node_n_mesh_renderer_sys
node_n_renderer_sys -->|"delegates"| node_n_fs_renderer_sys
node_n_renderer_sys -->|"delegates"| node_n_shader_testbed_sys
node_n_mesh_renderer_sys -->|"loads"| node_n_shaders
node_n_fs_renderer_sys -->|"loads"| node_n_shaders
node_n_shader_testbed_sys -->|"loads"| node_n_shaders
node_n_renderer_sys -->|"renders with"| node_n_legitvulkan
node_n_renderer_sys -->|"overlays"| node_n_imgui
node_n_mesh_renderer_sys -->|"consumes"| node_n_triangles
node_n_cloth_scene -->|"creates"| node_n_particles
node_n_cloth_scene -->|"creates"| node_n_links
node_n_mg_scene -->|"creates"| node_n_particles
node_n_mg_scene -->|"creates"| node_n_links
node_n_cloth_scene -->|"loads from"| node_n_scenes
node_n_mg_scene -->|"loads from"| node_n_scenes
node_n_anim_sys -->|"loads"| node_n_animations
node_n_renderer_sys -->|"uses"| node_n_glm

click node_n_main "https://github.com/raikiri/legitparticles/blob/master/src/main.cpp"
click node_n_window_sys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/Window.h"
click node_n_input_sys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/Input.h"
click node_n_camera_sys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/Camera.h"
click node_n_renderer_sys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/Renderer.h"
click node_n_mesh_renderer_sys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/MeshRenderer.h"
click node_n_fs_renderer_sys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/FullscreenRenderer.h"
click node_n_shader_testbed_sys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/ShaderTestbedRenderer.h"
click node_n_anim_sys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/SkeletalAnimation.h"
click node_n_phys_anim_sys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/PhysicsAnimation.h"
click node_n_vbd_phys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/VBDPhysics.h"
click node_n_sparse_phys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/SparsePhysics.h"
click node_n_mg_phys "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/MultigridPhysics.h"
click node_n_phys_common "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/PhysicsCommon.h"
click node_n_phys_graphs "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/PhysicsGraphs.h"
click node_n_phys_ctx "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Context/PhysicsData.h"
click node_n_render_ctx "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Context/RendererData.h"
click node_n_ui_ctx "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Context/WindowData.h"
click node_n_particles "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Components/ParticleComponent.h"
click node_n_links "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Components/LinkComponent.h"
click node_n_triangles "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Components/TriangleComponent.h"
click node_n_cloth_scene "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Scenes/SimpleClothScene.h"
click node_n_mg_scene "https://github.com/raikiri/legitparticles/blob/master/src/ECS/Scenes/MultigridClothScene.h"
click node_n_shaders "https://github.com/raikiri/legitparticles/tree/master/bin/data/Shaders"
click node_n_scenes "https://github.com/raikiri/legitparticles/tree/master/bin/data/Scenes"
click node_n_animations "https://github.com/raikiri/legitparticles/tree/master/bin/data/Animations/WalkTest"
click node_n_glfw "https://github.com/raikiri/legitparticles/tree/master/dependencies/glfw"
click node_n_glm "https://github.com/raikiri/legitparticles/tree/master/dependencies/glm"
click node_n_imgui "https://github.com/raikiri/legitparticles/tree/master/dependencies/imgui"
click node_n_legitvulkan "https://github.com/raikiri/legitparticles/tree/master/dependencies/LegitVulkan"

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_n_main toneBlue
class node_n_window_sys,node_n_input_sys,node_n_camera_sys,node_n_phys_ctx,node_n_particles,node_n_links,node_n_triangles,node_n_cloth_scene,node_n_mg_scene toneAmber
class node_n_phys_anim_sys,node_n_vbd_phys,node_n_sparse_phys,node_n_mg_phys,node_n_phys_common,node_n_phys_graphs toneMint
class node_n_renderer_sys,node_n_mesh_renderer_sys,node_n_fs_renderer_sys,node_n_shader_testbed_sys,node_n_anim_sys,node_n_render_ctx,node_n_ui_ctx toneRose
class node_n_shaders,node_n_scenes,node_n_animations toneIndigo
class node_n_glfw,node_n_glm,node_n_imgui,node_n_legitvulkan toneTeal
```

## Components

### App Runtime

Executable startup, frame loop, and top-level orchestration.

- [Main](https://github.com/raikiri/legitparticles/blob/master/src/main.cpp): entrypoint · Program startup and top-level frame loop wiring. · `src/main.cpp`

### ECS Layer

Entity/component data and frame-stage systems.

- [Window](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/Window.h): system · Creates and drives the application window and event lifecycle. · `src/ECS/Systems/Window.h`
- [Input](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/Input.h): system · Polls and normalizes user input into shared ECS state. · `src/ECS/Systems/Input.h`
- [Camera](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/Camera.h): system · Updates view controls and camera motion. · `src/ECS/Systems/Camera.h`
- [Physics Data](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Context/PhysicsData.h): context · Shared simulation state passed between ECS systems. · `src/ECS/Context/PhysicsData.h`
- [Particles](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Components/ParticleComponent.h): Per-entity particle state. · `src/ECS/Components/ParticleComponent.h`
- [Links](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Components/LinkComponent.h): Constraint links between particles. · `src/ECS/Components/LinkComponent.h`
- [Triangles](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Components/TriangleComponent.h): Surface topology for cloth and mesh-like entities. · `src/ECS/Components/TriangleComponent.h`
- [Cloth Scene](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Scenes/SimpleClothScene.h): scene · Simple cloth setup for the demo runtime. · `src/ECS/Scenes/SimpleClothScene.h`
- [Multigrid Scene](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Scenes/MultigridClothScene.h): scene · Cloth setup tailored to the multigrid solver path. · `src/ECS/Scenes/MultigridClothScene.h`

### Physics

Constraint-based cloth/particle solvers and shared solver infrastructure.

- [Physics Animation](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/PhysicsAnimation.h): system · Bridges physics state with animation-style demo behavior. · `src/ECS/Systems/PhysicsAnimation.h`
- [VBD Solver](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/VBDPhysics.h): solver · Main constraint-projection particle/cloth solver. · `src/ECS/Systems/VBDPhysics.h`
- [Sparse Solver](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/SparsePhysics.h): solver · Sparse-matrix oriented physics path and supporting iterations. · `src/ECS/Systems/SparsePhysics.h`
- [Multigrid Solver](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/MultigridPhysics.h): solver · Multigrid cloth/constraint solver variant. · `src/ECS/Systems/MultigridPhysics.h`
- [Physics Common](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/PhysicsCommon.h): support · Shared solver utilities and data preparation. · `src/ECS/Systems/PhysicsCommon.h`
- [Physics Graphs](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/PhysicsGraphs.h): support · Constraint graph construction and iteration structure. · `src/ECS/Systems/PhysicsGraphs.h`

### Rendering

Rendering paths, UI, and graphics-facing context.

- [Renderer](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/Renderer.h): system · Coordinates frame rendering from simulation state. · `src/ECS/Systems/Renderer.h`
- [Mesh Renderer](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/MeshRenderer.h): system · Renders mesh geometry for scene content and demos. · `src/ECS/Systems/MeshRenderer.h`
- [Fullscreen Pass](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/FullscreenRenderer.h): system · Runs screen-space or post-process style rendering. · `src/ECS/Systems/FullscreenRenderer.h`
- [Shader Testbed](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/ShaderTestbedRenderer.h): system · Interactive shader experimentation and rendering probes. · `src/ECS/Systems/ShaderTestbedRenderer.h`
- [Skeletal Animation](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Systems/SkeletalAnimation.h): system · Advances imported animation data for demo playback. · `src/ECS/Systems/SkeletalAnimation.h`
- [Render Data](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Context/RendererData.h): context · Renderer-facing shared state and frame resources. · `src/ECS/Context/RendererData.h`
- [UI Data](https://github.com/raikiri/legitparticles/blob/master/src/ECS/Context/WindowData.h): context · ImGui and interaction state for runtime controls. · `src/ECS/Context/WindowData.h`

### Assets

Runtime content and shader artifacts.

- [Shaders](https://github.com/raikiri/legitparticles/tree/master/bin/data/Shaders): assets · Precompiled runtime shader artifacts and sources. · `bin/data/Shaders`
- [Scenes](https://github.com/raikiri/legitparticles/tree/master/bin/data/Scenes): assets · Data-driven scene definitions loaded at runtime. · `bin/data/Scenes`
- [Animations](https://github.com/raikiri/legitparticles/tree/master/bin/data/Animations/WalkTest): assets · Imported animation content used by demo systems. · `bin/data/Animations/WalkTest`

### Dependencies

Vendored third-party libraries that define major platform and math boundaries.

- [GLFW](https://github.com/raikiri/legitparticles/tree/master/dependencies/glfw): platform · Windowing, input, and OpenGL/Vulkan context handling. · `dependencies/glfw`
- [GLM](https://github.com/raikiri/legitparticles/tree/master/dependencies/glm): math · Vector and matrix math foundation. · `dependencies/glm`
- [ImGui](https://github.com/raikiri/legitparticles/tree/master/dependencies/imgui): ui · Immediate-mode debug and control UI. · `dependencies/imgui`
- [LegitVulkan](https://github.com/raikiri/legitparticles/tree/master/dependencies/LegitVulkan): render backend · Local Vulkan-oriented rendering dependency. · `dependencies/LegitVulkan`

## Connections

- Main → Window: starts · Initializes the window/runtime layer and enters the frame loop.
- Main → Input: registers · Sets up input handling for interactive control.
- Main → Camera: registers · Creates camera control as part of scene setup.
- Main → VBD Solver: selects · Chooses the main cloth/particle solver path.
- Main → Renderer: drives · Runs simulation and rendering each frame.
- Window → GLFW: uses · Relies on GLFW for windowing and events.
- Input → GLFW: reads · Consumes window and device input events.
- Camera → Render Data: updates · Writes view transforms into shared render state.
- Input → UI Data: updates · Feeds interaction state and UI toggles.
- VBD Solver → Physics Data: writes · Updates particle and constraint simulation state.
- VBD Solver → Particles: mutates · Advances particle positions and velocities.
- VBD Solver → Links: solves · Projects link constraints during iterations.
- VBD Solver → Physics Graphs: depends on · Uses graph structure to organize constraint solving.
- Sparse Solver → Physics Common: shares · Reuses common sparse/solver utilities.
- Multigrid Solver → Physics Common: shares · Reuses common multigrid support code.
- Multigrid Solver → Physics Graphs: depends on · Uses graph organization for multigrid iteration structure.
- Physics Animation → Physics Data: reads · Consumes simulation output for animation coupling.
- Physics Animation → Skeletal Animation: coordinates · Aligns physics-driven motion with animation playback.
- Renderer → Render Data: reads · Consumes shared rendering state and resources.
- Renderer → Mesh Renderer: delegates · Routes mesh drawing through a specialized renderer.
- Renderer → Fullscreen Pass: delegates · Uses fullscreen passes for screen-space rendering.
- Renderer → Shader Testbed: delegates · Exposes shader testing as part of the render path.
- Mesh Renderer → Shaders: loads · Consumes mesh shader binaries and sources.
- Fullscreen Pass → Shaders: loads · Consumes fullscreen shader assets.
- Shader Testbed → Shaders: loads · Uses testbed shaders from the asset tree.
- Renderer → LegitVulkan: renders with · Uses the local Vulkan rendering backend.
- Renderer → ImGui: overlays · Draws runtime controls and debug UI.
- Mesh Renderer → Triangles: consumes · Uses topology components for drawable geometry.
- Cloth Scene → Particles: creates · Defines initial particle layout for cloth demos.
- Cloth Scene → Links: creates · Sets up cloth constraints.
- Multigrid Scene → Particles: creates · Defines particles for the multigrid cloth setup.
- Multigrid Scene → Links: creates · Sets up constraints for multigrid cloth.
- Cloth Scene → Scenes: loads from · Scene configuration is data-driven from JSON assets.
- Multigrid Scene → Scenes: loads from · Scene configuration is data-driven from JSON assets.
- Skeletal Animation → Animations: loads · Consumes imported animation content.
- Renderer → GLM: uses · Uses GLM for math and transforms.
