Skip to main content

​
Overview

The PData interface defines the complete state and configuration of a particle in the simulation. Each particle maintains its physical properties, motion state, applied forces, and event triggers.

​
Interface Definition

export interface PData {
  id: number;
  p0_fis: [number, number, number];
  v0_fis: [number, number, number];
  a0_fis: [number, number, number];
  fx: string;
  fy: string;
  fz: string;
  curr_fis: [number, number, number];
  curr_vel: [number, number, number];
  t: number;
  trail_three: [number, number, number][];
  enSuelo: boolean;
  color: string;
  mass: number;
  isMassless: boolean;
  forces: Force[];
  events: ParticleEvent[];
}

​
Fields

​
id
number
required
Unique identifier for the particle. Used to reference and manage individual particles in the simulation.

​
Initial Conditions

​
p0_fis
[number, number, number]
required
Initial position vector in 3D space [x, y, z]. Defines where the particle starts in the simulation.
"p0_fis": [20, 0, 0]
​
v0_fis
[number, number, number]
required
Initial velocity vector [vx, vy, vz]. Defines the particle’s starting velocity in each dimension.
"v0_fis": [0, 8, 0]
​
a0_fis
[number, number, number]
required
Initial acceleration vector [ax, ay, az]. Typically set to [0, 0, 0] unless starting with specific acceleration.
"a0_fis": [0, 0, 0]

​
Force Formulas

​
fx
string
Formula string for force in x-direction. Can reference variables t, x, y, z and use Math functions. Leave empty or “0” for no force.
"fx": "-x * abs(cos(t*0.2))"
​
fy
string
Formula string for force in y-direction. Supports mathematical expressions with time and position variables.
"fy": "-y * abs(cos(t*0.2))"
​
fz
string
Formula string for force in z-direction. Can include complex expressions with trigonometric functions.
"fz": "-z * 0.5 + 20 * tanh(sin(t + 0.31))"

​
Current State

​
curr_fis
[number, number, number]
required
Current position vector [x, y, z]. Updated each simulation step based on velocity and acceleration.
​
curr_vel
[number, number, number]
required
Current velocity vector [vx, vy, vz]. Updated each step based on forces and acceleration.
​
t
number
required
Elapsed simulation time in seconds for this particle. Incremented by deltaT each step.

​
Visualization

​
trail_three
[number, number, number][]
required
Array of position points forming the particle’s trajectory trail. Each element is a [x, y, z] position.Used to render the motion path when path visualization is enabled.
​
color
string
required
Hexadecimal color code for the particle. Supports standard CSS color formats.
"color": "#ff00ff"

​
Physics Properties

​
mass
number
required
Particle mass in kilograms. Affects force calculations via Newton’s second law (F = ma).
"mass": 5
​
enSuelo
boolean
required
Ground contact flag. true when particle is touching the ground (y ≤ 0), enabling friction calculations.
​
isMassless
boolean
required
Kinematic mode flag. When true, the particle ignores forces and follows purely kinematic motion (constant velocity).

​
Advanced Systems

​
forces
Force[]
required
Array of force objects applied to the particle. Forces are evaluated and combined each simulation step.See Force System for details.
"forces": [
  {
    "id": 1,
    "vec": ["-x * 0.5", "-y * 0.5", "20"]
  }
]
​
events
ParticleEvent[]
required
Array of event triggers that can modify particle behavior when conditions are met.See Event System for details.
"events": [
  {
    "id": 1,
    "name": "Ground Impact",
    "conditions": [{"variable": "y", "operator": "<=", "value": 0}],
    "conditionLogic": "AND",
    "actions": [{"type": "changeColor", "payload": "#ff0000"}],
    "triggered": false,
    "enabled": true
  }
]

​
Creating Particles

​
Basic Particle

{
  "id": 1,
  "color": "#00ff00",
  "mass": 1,
  "p0_fis": [0, 10, 0],
  "v0_fis": [5, 0, 0],
  "forces": []
}

​
Particle with Forces

{
  "id": 9001,
  "color": "#ff00ff",
  "mass": 5,
  "p0_fis": [20, 0, 0],
  "v0_fis": [0, 8, 0],
  "forces": [
    {
      "id": 1,
      "vec": [
        "-x * abs(cos(t*0.2))",
        "-y * abs(cos(t*0.2))",
        "-z * 0.5 + 20 * tanh(sin(t + 0.31))"
      ]
    }
  ]
}

​
Kinematic Particle

{
  "id": 100,
  "color": "#0000ff",
  "mass": 1,
  "isMassless": true,
  "p0_fis": [0, 0, 0],
  "v0_fis": [10, 0, 0],
  "forces": []
}

​
Runtime Behavior

​
Initialization

When a particle is created:
  1. curr_fis is set to p0_fis
  2. curr_vel is set to v0_fis
  3. t is set to 0
  4. trail_three is initialized as empty array
  5. enSuelo is calculated based on initial y-position

​
Each Simulation Step

  1. Forces are evaluated from fx, fy, fz formulas and forces array
  2. Net force is calculated by summing all force components
  3. Acceleration is computed: a = F_net / mass (unless isMassless)
  4. Velocity is updated: v = v + a * deltaT
  5. Position is updated: p = p + v * deltaT
  6. Current position is added to trail_three
  7. Events are checked and triggered
  8. Time t is incremented by deltaT

Build docs developers (and LLMs) love

Get started for freeTalk to us