2d-collision

💥 Particle Physics Simulation

A lightweight and customisable JavaScript library for simulating particle physics, including collisions, gravity, and mouse interactivity. Perfect for creating dynamic visual effects.

🚀 Installation:

Option 1: via npm

npm install 2d-collision

🎮 Usage and Configuration

Functions:

The library provides the following key functions:

• createParticle(radius, mass, element, container) – Creates a single particle and adds it to the simulation.

  • radius(number) – determines particle's size
  • mass(number) – determines particle's weight
  • element(string) – the HTML element that you'd like to turn into a particle
  • container(string) – the HTML element that you'd like to act as the container for the particle

• createParticles(radii, masses, elements, container) – Creates multiple particles at once.

• editParticles() – Modify properties of particles by selecting them via their class. Function provides the following arguments:

  • particlesClass (string) – The class of the HTML elements representing the particles.
  • setVelX, setVelY (number) – Sets the velocity of the particles along the X and Y axes.
  • addVelX, addVelY (number) – Adds to the current velocity of the particles along the X and Y axes.
  • multiplyVelX, multiplyVelY (number) – Multiplies the current velocity of the particles along the X and Y axes.
  • setPosX, setPosY (number) – Sets the position of the particles along the X and Y axes.
  • addPosX, addPosY (number) – Adds to the current position of the particles along the X and Y axes.
  • multiplyPosX, multiplyPosY (number) – Multiplies the current position of the particles along the X and Y axes.
  • setRadii (number) – Sets the radii of the particles.
  • addRadii (number) – Adds to the current radii of the particles.
  • multiplyRadii (number) – Multiplies the current radii of the particles.
  • setMasses (number) – Sets the masses of the particles.
  • addMasses (number) – Adds to the current masses of the particles.
  • multiplyMasses (number) – Multiplies the current masses of the particles.
    

Example:

// Create a single particle
createParticle(10, 1, document.querySelector('#circle'), document.querySelector('#container'));

// Create multiple particles
createParticles(12, 3, document.querySelectorAll('.circle'), document.querySelector('#container'));

// Edit particles
editParticles({
    particlesClass: 'circle',
    setVelX: 5,
    addPosY: 10,
    multiplyRadii: 1.5
});

Global Configuration:

The library includes several global settings to control particle behavior:

• Particle.acceleration (Vector) – Controls gravity direction.
  Default: (0, 0.35)
  ➜ To edit values, assign like: Particle.acceleration.x = ..., Particle.acceleration.y = ...
• Particle.collisionDamping (number) – Reduces velocity after collisions.
  Default: 0.5
• Particle.enableCursorForce (boolean) – Enables or disables interactive forces from the cursor.
  Default: true
• Particle.cursorForce (number) – Strength of the cursor's interactive force.
  Default: 0.5
• Particle.containerPadding (number) – Sets padding around the container to prevent particles from touching edges.
  Default: 0

License: MIT
Contributing: Contributions welcome! Please feel free to submit a Pull Request.