Particle Editor

Opening the Particle Editor

To edit a particle’s properties, click on any particle in the Particles list in the GUI sidebar. The Particle Editor panel will open on the left side of the screen.

The simulation automatically pauses when you open the Particle Editor to prevent changes during motion.

Editor Interface Overview

The Particle Editor provides complete control over a particle’s physical properties, forces, and events:

ParticleEditor.tsx

interface ParticleEditorProps {
  sel: PData;              // Selected particle data
  onUpdatePart: (id: number, data: any) => void;
  onClose: () => void;
}

Calculation Modes

The simulator supports two physics calculation modes:

Kinematics Mode

Define position directly as functions of time f(t). Use when:

You know the exact trajectory equation
Working with parametric paths
Educational demonstrations of motion types

Button appearance: Green background with text “MODE: KINEMATICS f(t)“

Dynamics Mode

Define forces F(t, x, y, z) and let the engine compute motion using Newton’s laws. Use when:

Simulating realistic physics interactions
Working with force fields
Modeling particle interactions

Button appearance: Red background with text “MODE: DYNAMICS (FORCES)”

Click the mode button to toggle between kinematics and dynamics modes. The editor interface changes based on the selected mode.

Editing Initial Conditions

Initial Position

Set the starting position in 3D space:

Position Input

<label>Initial Position (X, Y, Z)</label>
<input type="number" value={sel.p0_fis[0]} /> // X coordinate
<input type="number" value={sel.p0_fis[1]} /> // Y coordinate
<input type="number" value={sel.p0_fis[2]} /> // Z coordinate

Coordinate System:

X: Forward/backward
Y: Left/right
Z: Up/down (Z=0 is the ground plane)

Initial Velocity

Set the starting velocity vector:

Velocity Input

<label>Initial Velocity (v0)</label>
<input type="number" value={sel.v0_fis[0]} /> // vx
<input type="number" value={sel.v0_fis[1]} /> // vy
<input type="number" value={sel.v0_fis[2]} /> // vz

Velocity is measured in meters per second (m/s). Positive Z velocity means upward motion.

Setting Mass (Dynamics Mode Only)

When in dynamics mode, you can set the particle’s mass:

Mass Input

<label>Mass (kg)</label>
<input 
  type="number" 
  value={sel.mass}
  onChange={(e) => onUpdatePart(sel.id, { mass: Number(e.target.value) })}
/>

Important considerations:

Mass affects how forces accelerate the particle (F = ma)
Heavier particles accelerate more slowly under the same force
Default mass is 1 kg
Minimum practical mass is 0.001 kg (to avoid division issues)

Managing Forces (Dynamics Mode)

Adding Forces

Click the ”+ ADD FORCE” button to create a new force vector:

Add Force

const addForce = () => {
  const newForce: Force = { id: Date.now(), vec: ["0", "0", "0"] };
  onUpdatePart(sel.id, { forces: [...sel.forces, newForce] });
};

Each force has three components:

Fx: Force in X direction (Newtons)
Fy: Force in Y direction (Newtons)
Fz: Force in Z direction (Newtons)

Editing Force Formulas

Each force component accepts a mathematical formula:

Fx: 10
Fy: 0
Fz: -5

Force Vector Display

Force Editor UI

{sel.forces.map((f, i) => (
  <div key={f.id}>
    <input type="text" value={f.vec[0]} placeholder="Fx" />
    <input type="text" value={f.vec[1]} placeholder="Fy" />
    <input type="text" value={f.vec[2]} placeholder="Fz" />
    <button onClick={() => deleteForce(f.id)}>X</button>
  </div>
))}

Removing Forces

Click the “X” button next to any force to remove it from the particle.

Removing all forces in dynamics mode means the particle will only be affected by gravity (if enabled) and initial velocity.

Managing Multiple Forces

The simulator supports multiple simultaneous forces on a single particle:

Forces are additive - all forces are summed to get the net force
Net force is calculated every frame: F_net = F1 + F2 + F3 + ...
Acceleration is computed using Newton’s second law: a = F_net / mass

Example: Spring System with Damping

Force 1 (Restoring Spring Force)

Fx: -10 * x
Fy: -10 * y  
Fz: -10 * z

Force 2 (Damping Force)
Fx: -0.5 * vx
Fy: -0.5 * vy
Fz: -0.5 * vz

Use multiple forces to separate different physical effects (springs, damping, external fields) for easier tuning and understanding.

Kinematics Mode Functions

In kinematics mode, define position functions directly:

Kinematics Input

<label>Functions f(t)</label>
<input placeholder="fx(t)" value={sel.fx} />
<input placeholder="fy(t)" value={sel.fy} />
<input placeholder="fz(t)" value={sel.fz} />

Examples:

fx(t): 10 * cos(t)
fy(t): 10 * sin(t)
fz(t): 0

In kinematics mode, gravity still affects the particle. Set fz(t) to compensate: fz(t): -0.5 * 9.81 * t^2 for free fall.

Setting Particle Color

Customize the particle’s visual appearance:

Color Picker

<label>Color</label>
<input 
  type="color" 
  value={sel.color}
  onChange={(e) => onUpdatePart(sel.id, { color: e.target.value })}
/>

Colors are stored in hex format (e.g., #ff00ff). The color picker provides a visual interface for selection.

Use different colors to distinguish particle groups or track individual particles in complex simulations.

Events Configuration

The Events section allows you to trigger actions based on conditions. See the Events Guide for detailed information.

Quick Overview

Events appear below the main editor with:

Event name (editable)
ON/OFF toggle (enable/disable)
Conditions list with AND/OR logic
Actions list (pause, changeColor)
Delete button (X)

Event Display

<label>Events ({sel.events?.length || 0})</label>
<button onClick={addEvent}>+ ADD EVENT</button>

Event Status Indicators:

Green background: Event has been triggered
Yellow border: Event is enabled
Gray border: Event is disabled
✓ Triggered: Shows when event conditions are met

Closing the Editor

Click the “CLOSE” button at the bottom of the editor to return to the main view:

Close Button

<button
  onClick={onClose}
  style={{ marginTop: 10, background: "#007bff", color: "white" }}
>
  CLOSE
</button>

Changes are applied immediately. Click CLOSE or select another particle to exit the editor.

Particle List Interactions

In the main GUI, the particle list offers additional interactions:

Click Actions

Left Click: Open particle editor
Right Click: Focus camera on particle
Shift + Click: Reset camera to default position

Particle Display

Particle Item

<div className="particle-item" style={{ color: part.color }}>
  <span>
    P-{part.id.toString().slice(-3)}
    {part.enSuelo ? "(Ground)" : ""}
  </span>
  <button onClick={deleteParticle}>x</button>
</div>

P-XXX: Last 3 digits of particle ID
(Ground): Appears when particle is touching ground (z=0)
x button: Delete the particle

Common Workflows

Creating a projectile

Add a new particle at desired height
Set initial velocity (e.g., vx=10, vy=0, vz=5)
Switch to Dynamics mode
Leave forces empty (gravity will act automatically)
Enable gravity in Environment settings
Click START

Creating a spring oscillator

Add particle at (10, 0, 0)
Set initial velocity (0, 0, 0)
Switch to Dynamics mode
Set mass to 1 kg
Add force: Fx=-10x, Fy=-10y, Fz=-10*z
Disable gravity
Click START

Creating a custom trajectory

Add particle at (0, 0, 0)
Switch to Kinematics mode
Set functions:
- fx(t): 10*cos(t)
- fy(t): 10*sin(t)
- fz(t): t*2
Click START to see the helix motion

Adding collision detection

Open particle editor
Scroll to Events section
Click ”+ ADD EVENT”
Set condition: z <= 0
Add action: Pause
The simulation will pause when particle hits ground

Best Practices

Start Simple: Begin with basic forces/functions and add complexity gradually
Use Descriptive Colors: Color-code particles by behavior or group
Monitor Events: Keep track of triggered events using the visual indicators
Test Incrementally: After each change, run a short simulation to verify behavior
Save Configurations: Use the SAVE button to preserve interesting setups

Editing a particle resets its time to t=0 and reinitializes position/velocity. Use PAUSE instead of editing if you want to inspect mid-simulation.

Formula Syntax

Learn the complete formula syntax for forces and functions

Events System

Configure advanced event-based behaviors

Get Started

Core Concepts

Guides

Opening the Particle Editor

Editor Interface Overview

Calculation Modes

Kinematics Mode

Dynamics Mode

Editing Initial Conditions

Initial Position

Initial Velocity

Setting Mass (Dynamics Mode Only)

Managing Forces (Dynamics Mode)

Adding Forces

Editing Force Formulas

Force Vector Display

Removing Forces

Managing Multiple Forces

Kinematics Mode Functions

Setting Particle Color

Events Configuration

Quick Overview

Closing the Editor

Particle List Interactions

Click Actions

Particle Display

Common Workflows

Best Practices

Formula Syntax

Events System

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Opening the Particle Editor

​Editor Interface Overview

​Calculation Modes

​Kinematics Mode

​Dynamics Mode

​Editing Initial Conditions

​Initial Position

​Initial Velocity

​Setting Mass (Dynamics Mode Only)

​Managing Forces (Dynamics Mode)

​Adding Forces

​Editing Force Formulas

​Force Vector Display

​Removing Forces

​Managing Multiple Forces

​Kinematics Mode Functions

​Setting Particle Color

​Events Configuration

​Quick Overview

​Closing the Editor

​Particle List Interactions

​Click Actions

​Particle Display

​Common Workflows

​Best Practices

​Related Topics

Formula Syntax

Events System

Build docs developers (and LLMs) love

Opening the Particle Editor

Editor Interface Overview

Calculation Modes

Kinematics Mode

Dynamics Mode

Editing Initial Conditions

Initial Position

Initial Velocity

Setting Mass (Dynamics Mode Only)

Managing Forces (Dynamics Mode)

Adding Forces

Editing Force Formulas

Force Vector Display

Removing Forces

Managing Multiple Forces

Kinematics Mode Functions

Setting Particle Color

Events Configuration

Quick Overview

Closing the Editor

Particle List Interactions

Click Actions

Particle Display

Common Workflows

Best Practices

Related Topics