๐ฎ Particle Physics Playground
A modular, extensible particle physics simulation framework built with Python and Pygame. Create complex physics simulations with particles, forces, collisions, and custom behaviors.
โจ Features
- Modular Architecture: Clean separation of concerns with entities, systems, renderers, and playgrounds
- Realistic Physics:
- Gravity and friction
- Elastic collisions between particles
- Boundary collision detection
- Air resistance and drag
- Configurable physics parameters
- Extensible Particles: Add custom properties and behaviors through extensions
- Multiple Renderers: Abstract renderer design (currently Pygame, easily extensible)
- Interactive Playground: Built-in controls for pausing, resetting, and observing simulations
๐ Quick Start
Installation
# Clone the repository
git clone <your-repo-url>
cd pygame-p1
# Install dependencies
pip install -r requirements.txt
Run a Demo
# Run the bouncing balls demo
python demos/bouncing_balls.py
๐ฏ Usage
Creating a Simple Simulation
from playground import BasePlayground
from entities import Particle, System
class MySimulation(BasePlayground):
def setup(self):
# Create particles
particle = Particle(x=400, y=100, mass=1.0, radius=10, color=(255, 100, 100))
particle.state.velocity_y = 50 # Initial downward velocity
self.add_particle(particle)
# Add a static platform
platform = Particle(x=400, y=500, mass=10.0, radius=30, color=(150, 150, 150))
platform.state.is_static = True
self.add_particle(platform)
# Run the simulation
sim = MySimulation()
sim.run()
Customizing Physics
from entities import System
# Create custom physics configuration
system = System()
system.physics.gravity = 500.0 # Increase gravity
system.physics.friction = 0.2 # Increase friction
system.physics.bounce_coefficient = 0.8 # More bouncy
system.physics.elasticity = 0.9 # Elastic collisions
# Use in playground
playground = BasePlayground(system=system)
๐ Project Structure
pygame-p1/
โโโ entities/ # Core entity definitions
โ โโโ particle/ # Particle entity and models
โ โ โโโ particle.py # Main particle class
โ โ โโโ models/
โ โ โ โโโ position.py # 3D position
โ โ โ โโโ state.py # Velocity, mass, etc.
โ โ โ โโโ extensions.py # Extension system
โ โ โโโ actions/
โ โ โโโ joining.py # Particle connections
โ โโโ environment/ # Environment container
โ โ โโโ environment.py
โ โโโ system/ # Physics system
โ โโโ system.py # System manager
โ โโโ physics_engine.py # Physics calculations
โ โโโ models/
โ โโโ physics.py # Physics configuration
โโโ renderer/ # Rendering abstraction
โ โโโ renderer.py # Pygame renderer
โโโ playground/ # Simulation orchestrator
โ โโโ playground.py # Main playground class
โโโ demos/ # Example simulations
โโโ bouncing_balls.py # Interactive demos
โโโ test.py
๐จ Architecture
Core Components
- Particle: The fundamental entity with position, state (velocity, mass, etc.), and extensible properties
- System: Manages physics configuration and the physics engine
- PhysicsEngine: Handles force application, collision detection, and integration
- Renderer: Abstract rendering interface with Pygame implementation
- Playground: Orchestrates particles, physics, and rendering in a simulation loop
Key Design Patterns
- Entity-Component Pattern: Particles can have extensions for modular functionality
- Abstract Factory: Renderer is abstracted for multiple implementations
- Observer Pattern: Forces are accumulated and applied each frame
- Strategy Pattern: Physics parameters can be swapped without code changes
๐ฎ Controls
When running a simulation:
- SPACE: Pause/Resume simulation
- R: Reset simulation
- ESC: Quit
๐ง Advanced Usage
Creating Custom Extensions
from dataclasses import dataclass
@dataclass
class CustomExtension:
custom_property: float = 0.0
def update(self, particle, dt):
# Custom behavior
pass
# Register extension
particle.register_extension('custom', CustomExtension)
Custom Forces
# Apply custom forces to particles
particle.apply_force('wind', fx=50.0, fy=0.0)
particle.apply_force('magnetic', fx=0.0, fy=-20.0)
# Forces are automatically cleared each frame after physics update
Creating Custom Renderers
from renderer import Renderer
class MyCustomRenderer(Renderer):
def draw_particle(self, particle):
# Custom drawing logic
pass
def draw_dot(self, surface, color, position, radius):
# Custom dot drawing
pass
๐งช Physics Parameters
The Physics configuration includes extensive parameters:
- Basic: gravity, friction, air_resistance, bounce_coefficient
- Material: mass, elasticity, viscosity
- Advanced: drag_coefficient, terminal_velocity, pressure, temperature
- And many more for complex simulations
See entities/system/models/physics.py for the complete list.
๐ Examples
Bouncing Balls Demo
Shows multiple particles with gravity, elastic collisions, and boundary bouncing.
Gravity Well Demo
Demonstrates particles with different masses falling and colliding.
Pyramid Collapse Demo
Creates a pyramid structure that collapses under gravity.
๐ ๏ธ Future Enhancements
- Particle-to-particle constraints (springs, rods)
- Force fields (gravity wells, magnetic fields)
- Particle emitters and particle systems
- Spatial partitioning for performance (quadtree)
- Recording and playback
- Different rendering backends (OpenGL, web canvas)
- Soft body physics
- Fluid simulation
๐ค Contributing
This is a modular framework designed to be extended! Feel free to:
- Add new particle extensions
- Create new physics behaviors
- Build custom renderers
- Design new simulation types
- Optimize the physics engine
๐ License
See LICENSE file for details.
๐ Acknowledgments
Built with Python and Pygame for educational and experimental purposes.
Happy Simulating! ๐