Particles and Lua

The command to set a particle system on a SceneObject is setParticleSystem, which takes a string. The string should be a ParticleScript program. Here's an example:

obj:setParticleSystem([[
  # Controllable parameters.
  uniform float3 gravity = [0,0,-10]
  uniform float1 spawnrate = 50
  uniform float3 randinit = [1,1,0.2]
  uniform float3 constinit = [0,0,3]

  # Particle state.
  varying float3 position
  varying float3 initpos
  varying float3 initvel

  # deletion and spawning, and initialization
  delete position.z < 0.0
  spawnsteady spawnrate
  select new
  initpos = host.position
  initvel = randinit * rand.negpos + constinit

  # Particle update code.
  select all
  position = trajectory(initpos, initvel, gravity, age)

  # rendering
  renderorbs pos:position color:[1,0,0,0.4] size:0.2
  renderorbs pos:position color:[1,0.6,0.6,1.0] size:0.1 add
]])

The scene object will immediately begin generating particles. You can remove the particle system by calling SceneObject:clearParticleSystem().

Adjusting Uniform Values

The Lua code can reach into the particle system and adjust the values of uniform attributes. To do this, use the methods SceneObject:particles, which returns the particle system handle, and the method ParticleSystem:setUniformValue:

obj:particles():setUniformValue("Main.spawnrate", 1.0)

When using commands like setUniformValue, you must refer to attributes using their extended name, which consists of the group name, a dot, and the attribute name. The default group name, if not specified in the particle system code, is "Main."

Particle Dissipation

Removing a particle system from a scene object using clearParticleSystem will instantly cause all the particles to disappear. Sometimes, you don't want the particles to vanish in a blink, sometimes you want them to dissipate in a more natural way. One way to achieve this is to have a uniform spawnrate variable in your particle system. To get rid of the particle system, set the spawn rate to zero. Then, give the particle system time for the particles to go away on their own. Finally, several seconds later, clear the particle system.