The basic particle emitter script shown in this recipe emits red particles that float upward. The basic particle emitter is designed to be a starting point from which other particle emitters can be created. Most of the particle emitters in this chapter used the basic particle emitter as a starting point. The basic particle emitter can be seen in action in Figure 4.1.

Figure 4.1: Basic Particle Emitter

    The script for the basic particle emitter can be seen in Listing 4.1.

Listing 4.1: Basic Particle Emitter (BasicParticle.lsl)

// From the book:
//
// Scripting Recipes for Second Life
// by Jeff Heaton (Encog Dod in SL)
// ISBN: 160439000X
// Copyright 2007 by Heaton Research, Inc.
//
// This script may be freely copied and modified so long as this header
// remains unmodified.
//
// For more information about this book visit the following web site:
//
// http://www.heatonresearch.com/articles/series/22/

generalParticleEmitterOn()                
{   
    llParticleSystem([                   
        PSYS_PART_FLAGS , 0 
    //| PSYS_PART_BOUNCE_MASK       //Bounce on object's z-axis
    | PSYS_PART_WIND_MASK           //Particles are moved by wind
    | PSYS_PART_INTERP_COLOR_MASK   //Colors fade from start to end
    | PSYS_PART_INTERP_SCALE_MASK   //Scale fades from beginning to end
    | PSYS_PART_FOLLOW_SRC_MASK     //Particles follow the emitter
    | PSYS_PART_FOLLOW_VELOCITY_MASK//Particles are created at the velocity of the emitter
    //| PSYS_PART_TARGET_POS_MASK   //Particles follow the target
    | PSYS_PART_EMISSIVE_MASK       //Particles are self-lit (glow)
    //| PSYS_PART_TARGET_LINEAR_MASK//Undocumented--Sends particles in straight line?
    ,
    
    //PSYS_SRC_TARGET_KEY , NULL_KEY,//The particles will head towards the specified key
    //Select one of the following for a pattern:
    //PSYS_SRC_PATTERN_DROP                 Particles start at emitter with no velocity
    //PSYS_SRC_PATTERN_EXPLODE              Particles explode from the emitter
    //PSYS_SRC_PATTERN_ANGLE                Particles are emitted in a 2-D angle
    //PSYS_SRC_PATTERN_ANGLE_CONE           Particles are emitted in a 3-D cone
    //PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY     Particles are emitted everywhere except for a 3-D cone
    
    PSYS_SRC_PATTERN,           PSYS_SRC_PATTERN_ANGLE_CONE
    
    ,PSYS_SRC_TEXTURE,           ""           //UUID of the desired particle texture, or inventory name
    ,PSYS_SRC_MAX_AGE,           0.0            //Time, in seconds, for particles to be emitted. 0 = forever
    ,PSYS_PART_MAX_AGE,          4.0            //Lifetime, in seconds, that a particle lasts
    ,PSYS_SRC_BURST_RATE,        0.5            //How long, in seconds, between each emission
    ,PSYS_SRC_BURST_PART_COUNT,  6              //Number of particles per emission
    ,PSYS_SRC_BURST_RADIUS,      10.0           //Radius of emission
    ,PSYS_SRC_BURST_SPEED_MIN,   .4             //Minimum speed of an emitted particle
    ,PSYS_SRC_BURST_SPEED_MAX,   .5             //Maximum speed of an emitted particle
    ,PSYS_SRC_ACCEL,             <0,0,1>    //Acceleration of particles each second
    ,PSYS_PART_START_COLOR,      <1,0,0>  //Starting RGB color
    ,PSYS_PART_END_COLOR,        <1,0,0>  //Ending RGB color, if INTERP_COLOR_MASK is on 
    ,PSYS_PART_START_ALPHA,      1.0            //Starting transparency, 1 is opaque, 0 is transparent.
    ,PSYS_PART_END_ALPHA,        1.0            //Ending transparency
    ,PSYS_PART_START_SCALE,      <.25,.25,.25>  //Starting particle size
    ,PSYS_PART_END_SCALE,        <1.5,1.5,1.5>  //Ending particle size, if INTERP_SCALE_MASK is on
    ,PSYS_SRC_ANGLE_BEGIN,       300 * DEG_TO_RAD //Inner angle for ANGLE patterns
    ,PSYS_SRC_ANGLE_END,         60 * DEG_TO_RAD//Outer angle for ANGLE patterns
    ,PSYS_SRC_OMEGA,             <0.0,0.0,0.0>  //Rotation of ANGLE patterns, similar to llTargetOmega()
            ]);
}

generalParticleEmitterOff()
{
    llParticleSystem([]);
}

default
{    
    state_entry()
    {
        generalParticleEmitterOn();
    }

    touch_start( integer num )            
    {
        // uncomment the following line to allow this effect to be turned off
        //state off;        
    }
}

state off
{
    state_entry()
    {
        generalParticleEmitterOff();
    }
    
    touch_start( integer num )        
    {
        state default;
    }
}

    Nearly all of the work of the basic particle emitter is performed by the call to llParticleSystem inside of the generalParticleEmitterOn function.

Creating a Particle Emitter

    A particle emitter is created by passing a list to the llParticleSystem function. This list is a series of name-value pairs. The majority of the code presented in Listing 4.1 creates this list.

    The first name-value pair in the list is PSYS_PART_FLAGS. This defines a number of flags that define how the particles behave. These flags can be combined using the bit-wise or operator(|). These flags are summarized in Table 4.1.

Table 4.1: PSYS_PART_FLAGS Flags

    A particle system should specify a pattern using the PSYS_SRC_PATTERN name-value pair. Table 4.2 lists the possible patterns that can be specified.

    The remaining name-value pairs are simply a name and a simple value such as a number, texture key, or vector. These name-value pairs are summarized in Table 4.3.

Table 4.3: Remaining Particle Emitter Name-Value Pairs

    By modifying these values, any sort of particle emitter script can be created. The basic particle emitter script presented in this recipe creates red particles. The script specifies a vector of <1,0,0> for the PSYS_PART_START_COLOR and PSYS_PART_END_COLOR. The value <1,0,0> is RGB for red. The particles start with a size of <.25,.25,.25> and end with a size of <1.5,1.5,1.5>. No texture is specified so the particles will be glowing spheres. To cause the particles to go up a PSYS_SRC_ACCEL of <0,0,1> is specified.

    Many of the remaining recipes in this chapter will simply modify the values of the basic particle script to create other effects. Once a particle system has been specified for a prim, that prim will continue to emit particles until the amount of time specified by PSYS_SRC_MAX_AGE elapses. If a value of zero was specified, the prim will continue to create particles indefinably. To stop the prim from producing particles, the llParticleSystem function call should be called with an empty set, as seen here:

llParticleSystem([]);

    Once an empty set has been specified to the particle system, no more particles will be produced.