Molecules - GPU Particle Simulation

A real-time GPU-accelerated particle physics simulation built in Unity. Particles are simulated using XPBD (Extended Position Based Dynamics) entirely on the GPU via compute shaders, supporting thousands of particles with distance constraints, collisions, and interactive forces.

How It Works

The simulation runs in a substep loop each FixedUpdate. Every substep:

1. Integrate - Apply gravity, predict new positions
2. Solve Constraints - XPBD distance constraints with Jacobi iteration and SOR (Successive Over-Relaxation)
3. Solve Collisions - Ground plane, sphere/capsule/box colliders, and particle-particle via spatial hashing
4. Update Velocities - Derive velocity from position change, apply damping

All particle data lives on the GPU. Constraint solving uses fixed-point atomic accumulation for parallel Jacobi execution, averaged with an SOR factor for faster convergence.

Scripts

Core

Script	Description
MoleculeManager.cs	Singleton that owns all GPU buffers, manages particles and constraints, and dispatches the compute shader substep loop. Entry point for adding particles, constraints, and triggering explosions.
MoleculeCompute.compute	HLSL compute shader containing all simulation kernels: integration, constraint solving (XPBD with damping), ground/collider/particle collisions with Coulomb friction, spatial hashing, and explosion impulse.

Generators

Generators are MonoBehaviours that spawn particles and constraints in Start().

Script	Description
CubeGenerator.cs	Spawns a 3D grid of particles and connects them with structural, shear, and body-diagonal distance constraints. Supports fixing top/bottom rows.
KNNGenerator.cs	Spawns a 3D grid and connects each particle to its K nearest neighbours. Uses partial selection sort and duplicate-pair detection.
VoxelGenerator.cs	Voxelizes an arbitrary mesh into particles. Uses Moller-Trumbore ray-triangle intersection to determine which grid points lie inside the mesh, then builds grid-based constraints. Removes the mesh after generation.

Colliders

Custom collider components that register with MoleculeManager and are resolved on the GPU each substep. All support Coulomb friction.

Script	Description
MoleculeSphereCollider.cs	Sphere collider defined by transform position and scale-derived radius.
MoleculeCapsuleCollider.cs	Capsule collider defined by two endpoints (along local Y) and a radius.
MoleculeBoxCollider.cs	Oriented box collider using the full transform (position, rotation, scale).

Rendering

Script	Description
MoleculeParticleRenderer.cs	Renders all particles as GPU-instanced meshes using Graphics.DrawMeshInstancedProcedural. Reads particle positions and colors directly from the GPU buffer.
MoleculeConstraintRenderer.cs	Renders distance constraints as lines between connected particles.

Interaction

Script	Description
ExplosionInput.cs	On mouse click, reads back particle data from the GPU, raycasts against particle spheres to find the click target, and triggers a radial velocity impulse via a dedicated compute kernel. Uses the new Input System.

Key Features

• XPBD with damping - Constraints support compliance (stiffness), damping, and breakable force thresholds
• Parallel Jacobi solver - Atomic fixed-point accumulation with SOR for stable parallel constraint solving
• Spatial hash particle collisions - O(n) particle-particle collision detection using a GPU linked-list hash table
• Coulomb friction - Static and kinetic friction on ground, colliders, and particle-particle contacts
• Mesh voxelization - Turn any closed mesh into a soft body via Moller-Trumbore inside/outside testing
• Explosion interaction - Click on particles to apply radial impulse forces

Setup

1. Ensure a MoleculeManager exists in the scene with the compute shader assigned
2. Add a generator (CubeGenerator, KNNGenerator, or VoxelGenerator) to spawn particles
3. Optionally add MoleculeSphereCollider / MoleculeCapsuleCollider / MoleculeBoxCollider components to GameObjects for collision boundaries
4. Add ExplosionInput to any GameObject for click-to-explode interaction
5. Add MoleculeParticleRenderer and optionally MoleculeConstraintRenderer for visualization