A real-time galaxy particle simulation in C++ and SFML — black holes pulling each other apart while stars swarm around them in glowing heatmap clouds.
- About
- How It Works
- Simulation Rules
- Rendering — Star Heatmap
- Preview
- Dependencies
- Building
- Usage
- Configuration
- Contributing
Gravity-Sim is a real-time N-body particle simulation built in C++ with SFML. It models a galaxy-like system where:
- Stars are gravitationally attracted to black holes, but exert no force on each other.
- Black holes are attracted to one another via Newtonian gravity.
The result is a dynamic, emergent system — stars spiral and cluster around black holes, which themselves orbit, merge, or slingshot across the simulation space. Stars are rendered as a density heatmap for performance, giving the simulation a visually rich, glowing nebula-like aesthetic.
The simulation runs each frame as follows:
- Black hole gravity — Each black hole exerts a gravitational pull on every other black hole using the inverse-square law:
F = G * m₁ * m₂ / r². - Star attraction — Each star calculates its attraction toward every black hole and updates its velocity accordingly. Stars do not interact with each other.
- Integration — Positions and velocities are updated using a simple Euler integration step each frame.
- Rendering — Stars are accumulated into a heatmap texture; the brighter a region, the more stars are present. Black holes are drawn as distinct objects on top.
| Entity | Attracted to Stars? | Attracted to Black Holes? | Exerts force on others? |
|---|---|---|---|
| ⭐ Star | ✗ | ✅ | ✗ |
| ⚫ Black Hole | ✗ | ✅ | ✅ (on other black holes) |
This asymmetry is the core design choice — it allows the simulation to remain performant (no O(n²) star-to-star calculations) while still producing visually compelling galaxy-like behaviour.
Rather than drawing each star as an individual shape, stars are rendered using a density heatmap approach:
- Each frame, star positions are accumulated into a 2D grid.
- Grid cells are mapped to colours based on density — sparse regions glow faintly, dense clusters burn bright.
- This technique dramatically improves performance at high particle counts and produces a visually striking, nebula-like result.
|
 |
| Real-time simulation | Star heatmap detail |
| Dependency | Version | Notes |
|---|---|---|
| CMake | 3.15+ | Build system |
| SFML | 2.5+ | Rendering & windowing |
| C++ Compiler | C++17 | MSVC (Visual Studio 2019+) recommended on Windows |
- CMake 3.15+
- SFML 2.5+ — installed or locatable via
CMAKE_PREFIX_PATH - A C++17-compatible compiler (MSVC recommended on Windows)
1. Clone the repository
git clone https://github.com/curtis-aln/Gravity-Sim.git
cd Gravity-Sim2. Create a build directory
mkdir build
cd build3. Configure with CMake
cmake ..If CMake cannot find SFML automatically, point it to your SFML installation:
cmake .. -DCMAKE_PREFIX_PATH="C:/path/to/SFML"4. Build
cmake --build . --config Release5. Run
./GravitySim # Linux / macOS
GravitySim.exe # WindowsWindows note: Ensure the SFML DLLs (e.g.
sfml-graphics-2.dll,sfml-window-2.dll,sfml-system-2.dll) are in the same directory as the compiled executable, or that SFML is on your systemPATH.
Run the executable — a window will open and the simulation starts immediately.
./GravitySimThe simulation runs in real time. Black holes move and interact with each other while stars swarm around them. Close the window to exit.
All simulation parameters are hardcoded in the source files under src/. Key values to look for and adjust:
| Parameter | Description |
|---|---|
STAR_COUNT |
Total number of star particles |
BLACK_HOLE_COUNT |
Number of black holes in the simulation |
GRAVITATIONAL_CONSTANT |
Scales the strength of gravitational attraction |
BLACK_HOLE_MASS |
Mass of each black hole (affects pull strength) |
STAR_MASS |
Mass of each star (affects how strongly it's attracted) |
WINDOW_WIDTH / WINDOW_HEIGHT |
Simulation window resolution |
SOFTENING_FACTOR |
Prevents force singularities at very close range |
After editing any parameter, rebuild the project using the steps in the Building section.
Contributions are welcome! If you'd like to add features (e.g. configurable parameters, additional force models, trails, collision/absorption), fix a bug, or improve performance:
- Fork the repository
- Create a new branch (
git checkout -b feature/your-feature) - Commit your changes (
git commit -m 'Add your feature') - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
Please include a brief description of what changed and why.
- Newton's Law of Universal Gravitation — the physics model underpinning the simulation
- SFML documentation — rendering library used in this project