Skip to main content

​
Get Started in Minutes

This guide will walk you through creating your first particle simulation. You’ll learn how to create a particle, apply forces, and observe the resulting motion.
No installation required! Use the live demo to follow along directly in your browser.

​
Your First Simulation

1

Access the Simulator

Open the live demo in your browser:
https://particle-simulator-psy.netlify.app/
Or clone and run locally (see Installation):
git clone https://github.com/Gab-Cupe/Particle-Simulator.git
cd Particle-Simulator
npm install
npm run dev
You’ll see a 3D view with a control panel on the right side.
2

Create Your First Particle

In the SIMULATOR panel on the right:
  1. Expand the “New Particle” section
  2. Enter initial position coordinates:
    • X: 10
    • Y: 10
    • Z: 0
  3. Click the ”+ ADD PARTICLE” button
A new particle will appear in the 3D view at position (10, 10, 0). The particle list will show your new particle as “P-001”.
3

Configure the Particle

Click on the particle “P-001” in the Particles list to open the PHYSICS EDITOR panel on the left.You’ll see several configuration options:
  • Calculation Mode: Toggle between Kinematics and Dynamics
  • Initial Position: Current position (X, Y, Z)
  • Mass: Particle mass in kg (default: 1)
  • Forces: Mathematical expressions for forces
  • Initial Velocity: Starting velocity vector
Leave the mode on “MODE: DYNAMICS (FORCES)” for this tutorial. We’ll use force-based physics.
4

Add a Simple Harmonic Force

In the PHYSICS EDITOR:
  1. Scroll to the “Forces F(t, x, y, z) (N)” section
  2. Click ”+ ADD FORCE”
  3. You’ll see three input fields for Fx, Fy, and Fz
  4. Enter the following force components: 
    Fx: -x
Fy: -y
Fz: 0
This creates a restoring force that pulls the particle toward the origin - a classic harmonic oscillator!

​
Understanding the Force Formula

  • Fx = -x: Force in X direction proportional to X position (pulls back to center)
  • Fy = -y: Force in Y direction proportional to Y position (pulls back to center)
  • Fz = 0: No force in Z direction
The negative signs mean the force always points toward the origin.
5

Start the Simulation

  1. Click “CLOSE” to exit the particle editor
  2. In the main control panel, expand the “Controls” section
  3. Click the “START” button
Watch your particle oscillate! It will move in circular or elliptical paths around the origin, demonstrating simple harmonic motion.

​
Controls During Simulation

  • PAUSE: Stop the simulation at any time
  • RESET: Return particles to initial positions and velocities
  • Camera: Click and drag to rotate, scroll to zoom, right-click to pan
6

Experiment with Different Forces

Try modifying the forces to see different behaviors:

​
Damped Oscillation

Fx: -x * 0.5
Fy: -y * 0.5
Fz: 0

​
Pulsing Vortex

Fx: -x * abs(cos(t*0.2))
Fy: -y * abs(cos(t*0.2))
Fz: 0

​
Hyperbolic Motion

Fx: -x
Fy: -2.25 * y
Fz: sin(t * 0.5) * 5
Click PAUSE, edit the particle, update forces, and click START again to see the new behavior.

​
Available Variables and Functions

When writing force formulas, you have access to:

​
Variables

VariableDescription
tElapsed time in seconds
x, y, zCurrent particle position on each axis

​
Mathematical Functions

CategoryFunctionsExample
Trigonometrysin(n), cos(n), tan(n), atan2(y, x)10 * sin(t)
Hyperbolicsinh(n), cosh(n), tanh(n)20 * tanh(sin(t))
Logs & Powersqrt(n), log(n), log10(n), ^ or **log(t + 1)
Utilityabs(n), floor(n), ceil(n), round(n)abs(x)
Advancedmin(a, b), max(a, b), random(), sign(n)max(x, y)

​
Mathematical Constants

ConstantValue (Approx)
PI3.14159
E2.718
SQRT21.414

​
Visualization Options

Enhance your simulation with these visualization features:

​
Environment Settings

In the Environment section:
  • Gravity: Toggle global downward gravitational acceleration
  • Trail: Show particle motion paths
  • Axes: Display X, Y, Z coordinate axes
  • Grid: Show the ground plane grid
  • Particles: Toggle particle visibility
  • Particle Size: Adjust visual size of particles (0.1 - 3.0)

​
Force Display Modes

Click the Forces Display button to cycle through:
  1. Forces: OFF - No force vectors shown
  2. Forces: RESULTANT - Show net force vector
  3. Forces: INDIVIDUAL - Show each force component separately

​
Physics Parameters

  • Ground Friction: Damping coefficient when particles touch ground (0.0 - 2.0)
  • Delta T: Time step for simulation (0.001 - 0.1)
    • Smaller values = more accurate but slower
    • Larger values = faster but less accurate

​
Load the Example Configuration

Want to see a spectacular pre-built simulation?
  1. Click the “VIEW EXAMPLE” button in the control panel
  2. Click “START” to watch 20 particles in a synchronized vortex pattern
The example demonstrates:
  • Multiple particles with coordinated initial conditions
  • Complex force expressions: -x * abs(cos(t*0.2)) (pulsing vortex)
  • Hyperbolic vertical motion: -z * 0.5 + 20 * tanh(sin(t))
  • Phase-shifted behavior for visual appeal

​
Next Steps

Installation Guide

Set up the development environment on your local machine

Configuration Reference

Learn about all particle properties and simulation settings

Trajectory Examples

Explore more complex simulations and patterns

Data Structures

Dive into the technical details and data structures
If your simulation runs slowly or particles behave erratically, try:
  • Reducing the number of particles
  • Decreasing Delta T for better accuracy
  • Simplifying force expressions
  • Disabling trails and force visualizations

Build docs developers (and LLMs) love

Get started for freeTalk to us