💨 Particle System

The engine’s Particle System allows the creation of dynamic visual effects such as fire, smoke, sparks, rain or explosions. It is fully compatible with hierarchy, layers and visibility, and can work independently or as a child of any object.

⚙️ General Structure

A particle system is defined as an object of type ParticleSystem:

{
  "type": "ParticleSystem",
  "playOnStart": true,
  "looping": true,
  "simulationSpace": "local",
  "startDelay": 0,
  "destroyWhenDone": false,
  "particleData": { ... }
}

• playOnStart → Automatically starts emitting when pressing Play.
• looping → If true, the system restarts when its duration ends.
• simulationSpace → Controls whether particles move with the emitter (local) or remain fixed in the world (world).
• startDelay → Delays the beginning of the emission (in seconds).
• destroyWhenDone → Destroys the system when it ends and no particles remain active (only if looping = false).

🌪️ particleData Parameters

{
  "rate": 20,
  "life": 1.5,
  "speed": 100,
  "spread": 6.283,
  "color": "#ffaa00",
  "gravity": 0,
  "texture": "spark.png",
  "sizeMin": 4,
  "sizeMax": 12,
  "opacityMin": 0.5,
  "opacityMax": 1,
  "duration": 5
}

• rate → Particles emitted per second.
• life → Lifespan of each particle (seconds).
• speed → Initial speed of particles.
• spread → Emission angle in radians (Math.PI * 2 = full circle).
• color → Base color of particles.
• gravity → Vertical acceleration applied during their life.
• texture → Image used as particle sprite.
• sizeMin / sizeMax → Random minimum and maximum particle size.
• opacityMin / opacityMax → Random minimum and maximum opacity.
• duration → How long the system keeps emitting.

🧭 Simulation Modes

• 🌍 World: particles remain in world space. If the emitter moves, particles stay where they were created.
• 📦 Local: particles follow the emitter’s position, rotation and scale. Ideal for fire, smoke or effects attached to an object.

⏱️ System Lifecycle

• playOnStart starts emission automatically.
• startDelay delays the beginning of the emission.
• looping restarts emission when duration ends.
• destroyWhenDone removes the system when no active particles remain (if loop is disabled).

🧩 Hierarchy & Behaviour

A particle system can be the child of any object. When it is, it inherits position, rotation and scale like any other engine object.

• If the parent rotates, particles also rotate (only in local mode).
• If the parent is hidden or inactive, the system stops drawing particles.

🎨 Practical Examples

🔥 Fire (loop + local)

{
  "type": "ParticleSystem",
  "playOnStart": true,
  "looping": true,
  "simulationSpace": "local",
  "particleData": {
    "rate": 20,
    "life": 1.5,
    "speed": 50,
    "color": "#ff6600",
    "gravity": -30
  }
}

💥 Explosion (no loop + destroyWhenDone)

{
  "type": "ParticleSystem",
  "playOnStart": true,
  "looping": false,
  "destroyWhenDone": true,
  "particleData": {
    "rate": 200,
    "life": 0.8,
    "speed": 300,
    "spread": 6.283,
    "color": "#ffaa00"
  }
}

🌧️ Rain (world + infinite loop)

{
  "type": "ParticleSystem",
  "simulationSpace": "world",
  "looping": true,
  "particleData": {
    "rate": 100,
    "speed": 400,
    "gravity": 600,
    "life": 2,
    "color": "#66aaff"
  }
}

🚀 Performance Tips

• Use low rate on mobile devices (10–30).
• Avoid large textures; preferably <= 32×32 px.
• Disable visible when the system is off-screen.
• Use destroyWhenDone for single-shot effects (explosions, impacts, etc.).
• Combine local with looping for continuous attached effects.

▶️ Code Control: PlayParticles() and StopParticles()

Besides editor configuration, particle systems can be controlled dynamically through scripts using two key functions:

PlayParticles(obj);
StopParticles(obj);

// Alternative usage by passing the object name
PlayParticles("Particle");
StopParticles("Particle");

• PlayParticles(obj) → Immediately starts emitting particles, regardless of playOnStart.
• StopParticles(obj) → Stops emission, but keeps existing particles until they fade out.
• PlayParticles("Particle") → Passing the object name as parameter.
• StopParticles("Particle") → Passing the object name as parameter.

🔹 Simple Example

let ps = getObjectByName("ExplosionFX");
PlayParticles(ps);

🔹 Stop Emission

StopParticles(getObjectByName("SmokeExit"));

🔹 Triggering After an Event (e.g., collision)

function OnCollision(obj, other) {
    let fx = getObjectByName("HitFX");
    PlayParticles(fx);
}

🔹 Delayed Play

Timer(1.2, () => {
  PlayParticles(getObjectByName("Sparks"));
});

📌 Summary