How raikiri/legitparticles works
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: Renderer.h Renderer · main.cpp Main · VBDPhysics.h VBD Solver · SimpleClothScene.h Cloth Scene
Components 30
App Runtime
Executable startup, frame loop, and top-level orchestration.
- Main · Program startup and top-level frame loop wiring.
src/main.cpp
ECS Layer
Entity/component data and frame-stage systems.
- Window · Creates and drives the application window and event lifecycle.
src/ECS/Systems/Window.h - Input · Polls and normalizes user input into shared ECS state.
src/ECS/Systems/Input.h - Camera · Updates view controls and camera motion.
src/ECS/Systems/Camera.h - Physics Data · Shared simulation state passed between ECS systems.
src/ECS/Context/PhysicsData.h - Particles · Per-entity particle state.
src/ECS/Components/ParticleComponent.h - Links · Constraint links between particles.
src/ECS/Components/LinkComponent.h - Triangles · Surface topology for cloth and mesh-like entities.
src/ECS/Components/TriangleComponent.h - Cloth Scene · Simple cloth setup for the demo runtime.
src/ECS/Scenes/SimpleClothScene.h - Multigrid 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 · Bridges physics state with animation-style demo behavior.
src/ECS/Systems/PhysicsAnimation.h - VBD Solver · Main constraint-projection particle/cloth solver.
src/ECS/Systems/VBDPhysics.h - Sparse Solver · Sparse-matrix oriented physics path and supporting iterations.
src/ECS/Systems/SparsePhysics.h - Multigrid Solver · Multigrid cloth/constraint solver variant.
src/ECS/Systems/MultigridPhysics.h - Physics Common · Shared solver utilities and data preparation.
src/ECS/Systems/PhysicsCommon.h - Physics Graphs · Constraint graph construction and iteration structure.
src/ECS/Systems/PhysicsGraphs.h
Rendering
Rendering paths, UI, and graphics-facing context.
- Renderer · Coordinates frame rendering from simulation state.
src/ECS/Systems/Renderer.h - Mesh Renderer · Renders mesh geometry for scene content and demos.
src/ECS/Systems/MeshRenderer.h - Fullscreen Pass · Runs screen-space or post-process style rendering.
src/ECS/Systems/FullscreenRenderer.h - Shader Testbed · Interactive shader experimentation and rendering probes.
src/ECS/Systems/ShaderTestbedRenderer.h - Skeletal Animation · Advances imported animation data for demo playback.
src/ECS/Systems/SkeletalAnimation.h - Render Data · Renderer-facing shared state and frame resources.
src/ECS/Context/RendererData.h - UI Data · ImGui and interaction state for runtime controls.
src/ECS/Context/WindowData.h
Assets
Runtime content and shader artifacts.
- Shaders · Precompiled runtime shader artifacts and sources.
bin/data/Shaders - Scenes · Data-driven scene definitions loaded at runtime.
bin/data/Scenes - Animations · Imported animation content used by demo systems.
bin/data/Animations/WalkTest
Dependencies
Vendored third-party libraries that define major platform and math boundaries.
- GLFW · Windowing, input, and OpenGL/Vulkan context handling.
dependencies/glfw - GLM · Vector and matrix math foundation.
dependencies/glm - ImGui · Immediate-mode debug and control UI.
dependencies/imgui - LegitVulkan · Local Vulkan-oriented rendering dependency.
dependencies/LegitVulkan
Connections 36
- 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.