Particle Systems & Dynamic Effects

Control particle systems to create dynamic, living environments with atmospheric effects, animations, and visual enhancements. Particle systems are essential for creating realistic environmental effects like smoke, fire, rain, snow, and magical effects.

setParticleUpdateSpeed

setParticleUpdateSpeed(meshId: string, updateSpeed: number, [callback: Function])

Controls the update frequency of a particle system, affecting how smoothly particles animate and move. Higher values create smoother animations but may impact performance.

Parameters:

• meshId: string - ID of the emitter object (found via getNodeList)
• updateSpeed: number - Target update speed multiplier (1.0 = normal, 2.0 = double speed)

// Increase particle animation smoothness
api.setParticleUpdateSpeed('smoke_emitter_01', 2.0, function() {
  console.log('Particle update speed increased for smoother animation');
});

// Reduce update speed for performance optimization
api.setParticleUpdateSpeed('rain_system', 0.5, function() {
  console.log('Particle update speed reduced to save performance');
});

---

setParticleEmitRate

setParticleEmitRate(meshId: string, emitRate: number, [callback: Function])

Controls how many particles are emitted per second, directly affecting the density and intensity of the particle effect.

Parameters:

• meshId: string - ID of the emitter object (found via getNodeList)
• emitRate: number - Number of particles emitted per second

// Create intense fire effect
api.setParticleEmitRate('fire_emitter', 100, function() {
  console.log('Fire particle emission increased for dramatic effect');
});

// Create subtle ambient effect
api.setParticleEmitRate('dust_particles', 5, function() {
  console.log('Dust particle emission set to subtle level');
});

---

stopParticleSystem

stopParticleSystem(meshId: string, [callback: Function])

Stops a particle system completely, ceasing all particle emission and animation. Existing particles will fade out naturally.

Parameters:

• meshId: string - ID of the emitter object (found via getNodeList)

// Stop environmental effect
api.stopParticleSystem('snow_system', function() {
  console.log('Snow particle system stopped');
  
  // Update UI to reflect stopped state
  updateParticleControlUI('snow_system', false);
});

---

startParticleSystem

startParticleSystem(meshId: string, [callback: Function])

Starts or restarts a particle system, beginning particle emission and animation effects.

Parameters:

• meshId: string - ID of the emitter object (found via getNodeList)

// Start magical effect
api.startParticleSystem('magic_sparkles', function() {
  console.log('Magic sparkle particles started');
  
  // Update UI to reflect active state
  updateParticleControlUI('magic_sparkles', true);
});

Particle System Examples

Environmental Weather Effects:

class WeatherSystem {
  constructor() {
    this.activeWeather = null;
    this.weatherEffects = {
      rain: 'rain_particles',
      snow: 'snow_particles',
      fog: 'fog_particles'
    };
  }
  
  setWeather(weatherType) {
    // Stop current weather
    if (this.activeWeather) {
      api.stopParticleSystem(this.weatherEffects[this.activeWeather]);
    }
    
    // Start new weather
    if (weatherType && this.weatherEffects[weatherType]) {
      api.startParticleSystem(this.weatherEffects[weatherType], () => {
        // Adjust intensity based on weather type
        const emitRate = weatherType === 'rain' ? 200 : 50;
        api.setParticleEmitRate(this.weatherEffects[weatherType], emitRate);
      });
    }
    
    this.activeWeather = weatherType;
  }
}

const weather = new WeatherSystem();
weather.setWeather('rain'); // Start rain effect

Interactive Particle Controls:

function createParticleControls(particleSystemId) {
  const controlPanel = document.createElement('div');
  controlPanel.innerHTML = `
    <h3>Particle Controls: ${particleSystemId}</h3>
    <button onclick="toggleParticles('${particleSystemId}')">Toggle On/Off</button>
    <label>Emission Rate: <input type="range" min="1" max="200" value="50" 
           onchange="updateEmissionRate('${particleSystemId}', this.value)"></label>
    <label>Update Speed: <input type="range" min="0.1" max="3" step="0.1" value="1" 
           onchange="updateSpeed('${particleSystemId}', this.value)"></label>
  `;
  
  document.body.appendChild(controlPanel);
}

function toggleParticles(systemId) {
  // Check current state and toggle
  if (particleStates[systemId]) {
    api.stopParticleSystem(systemId);
    particleStates[systemId] = false;
  } else {
    api.startParticleSystem(systemId);
    particleStates[systemId] = true;
  }
}

function updateEmissionRate(systemId, rate) {
  api.setParticleEmitRate(systemId, parseInt(rate));
}

function updateSpeed(systemId, speed) {
  api.setParticleUpdateSpeed(systemId, parseFloat(speed));
}

Atmospheric Scene Controller:

class AtmosphereController {
  constructor() {
    this.scenes = {
      peaceful: {
        particles: ['gentle_breeze', 'floating_leaves'],
        settings: { emitRate: 10, updateSpeed: 0.8 }
      },
      dramatic: {
        particles: ['storm_clouds', 'lightning_sparks'],
        settings: { emitRate: 150, updateSpeed: 2.0 }
      },
      magical: {
        particles: ['fairy_dust', 'magic_orbs', 'sparkles'],
        settings: { emitRate: 75, updateSpeed: 1.5 }
      }
    };
  }
  
  setScene(sceneName) {
    const scene = this.scenes[sceneName];
    if (!scene) return;
    
    // Stop all current particles
    this.stopAllParticles();
    
    // Start scene-specific particles
    scene.particles.forEach(particleId => {
      api.startParticleSystem(particleId, () => {
        api.setParticleEmitRate(particleId, scene.settings.emitRate);
        api.setParticleUpdateSpeed(particleId, scene.settings.updateSpeed);
      });
    });
    
    console.log(`Atmosphere set to: ${sceneName}`);
  }
  
  stopAllParticles() {
    Object.values(this.scenes).forEach(scene => {
      scene.particles.forEach(particleId => {
        api.stopParticleSystem(particleId);
      });
    });
  }
}

const atmosphere = new AtmosphereController();
atmosphere.setScene('magical'); // Create magical atmosphere

Performance-Optimized Particle Manager:

class ParticlePerformanceManager {
  constructor() {
    this.activeSystems = new Map();
    this.performanceMode = 'high'; // 'high', 'medium', 'low'
  }
  
  setPerformanceMode(mode) {
    this.performanceMode = mode;
    this.adjustAllParticles();
  }
  
  adjustAllParticles() {
    const settings = this.getPerformanceSettings();
    
    this.activeSystems.forEach((systemInfo, systemId) => {
      api.setParticleEmitRate(systemId, systemInfo.baseEmitRate * settings.emitMultiplier);
      api.setParticleUpdateSpeed(systemId, systemInfo.baseUpdateSpeed * settings.speedMultiplier);
    });
  }
  
  getPerformanceSettings() {
    switch (this.performanceMode) {
      case 'low':
        return { emitMultiplier: 0.3, speedMultiplier: 0.5 };
      case 'medium':
        return { emitMultiplier: 0.6, speedMultiplier: 0.8 };
      case 'high':
      default:
        return { emitMultiplier: 1.0, speedMultiplier: 1.0 };
    }
  }
  
  registerSystem(systemId, baseEmitRate, baseUpdateSpeed) {
    this.activeSystems.set(systemId, {
      baseEmitRate,
      baseUpdateSpeed
    });
  }
}

Best Practices

Performance Optimization:

• Monitor frame rate when using multiple particle systems
• Reduce emission rates for distant or less important effects
• Use lower update speeds for background atmospheric effects

Visual Design:

• Layer multiple particle systems for complex effects
• Adjust emission rates based on scene importance
• Consider user preferences for visual effects intensity

User Experience:

• Provide controls to disable particles for performance
• Use particles to guide user attention and create atmosphere
• Balance visual impact with system performance