Particle system rules

Rules

Particle system rules are used in llParticleSystem() and llLinkParticleSystem() to create particle emitters. Once set, the particle system becomes a prim property and does not change on script resets.

System behavior rules

Note that the bitwise OR | is an operator and should be used inside a function, otherwise the script throws an error.

list behavior = [
    PSYS_PART_FLAGS, (
        // Comment unused masks
        PSYS_PART_BOUNCE_MASK |
        PSYS_PART_EMISSIVE_MASK |
        PSYS_PART_FOLLOW_SRC_MASK |
        PSYS_PART_FOLLOW_VELOCITY_MASK |
        PSYS_PART_INTERP_COLOR_MASK |
        PSYS_PART_INTERP_SCALE_MASK |
        PSYS_PART_RIBBON_MASK |
        PSYS_PART_TARGET_LINEAR_MASK |
        PSYS_PART_TARGET_POS_MASK |
        PSYS_PART_WIND_MASK
    )
];

System presentation rules

float radius;
float angle_begin;
float angle_end;
key target;

// Pick only one pattern below:
// PSYS_SRC_PATTERN_DROP
// PSYS_SRC_PATTERN_EXPLODE
// PSYS_SRC_PATTERN_ANGLE_CONE
// PSYS_SRC_PATTERN_ANGLE
// PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY
integer pattern = PSYS_SRC_PATTERN_DROP;

list presentation = [
    PSYS_PART_TARGET_LINEAR_MASK, pattern,
    PSYS_SRC_BURST_RADIUS, radius,
    PSYS_SRC_ANGLE_BEGIN, angle_begin,
    PSYS_SRC_ANGLE_END, angle_end,
    PSYS_SRC_TARGET_KEY, target
];

Particle appearance rules

vector color_start;
vector color_end;
float alpha_start;
float alpha_end;
vector scale_start;
vector scale_end;
string texture;
float glow_start;
float glow_end;

list appearance = [
    PSYS_PART_START_COLOR, color_start,
    PSYS_PART_END_COLOR, color_end,
    PSYS_PART_START_ALPHA, alpha_start,
    PSYS_PART_END_ALPHA, alpha_end,
    PSYS_PART_START_SCALE, scale_start,
    PSYS_PART_END_SCALE, scale_end,
    PSYS_SRC_TEXTURE, texture,
    PSYS_PART_START_GLOW, glow_start,
    PSYS_PART_END_GLOW, glow_end
];

Particle blending rules

// Pick only one of the blend functions below:
// PSYS_PART_BF_ONE
// PSYS_PART_BF_ZERO
// PSYS_PART_BF_DEST_COLOR
// PSYS_PART_BF_SOURCE_COLOR
// PSYS_PART_BF_ONE_MINUS_DEST_COLOR
// PSYS_PART_BF_ONE_MINUS_SOURCE_COLOR
// PSYS_PART_BF_SOURCE_ALPHA
// PSYS_PART_BF_ONE_MINUS_SOURCE_ALPHA
integer bf_source = PSYS_PART_BF_SOURCE_ALPHA;

// Pick only one of the blend functions below:
// PSYS_PART_BF_ONE
// PSYS_PART_BF_ZERO
// PSYS_PART_BF_DEST_COLOR
// PSYS_PART_BF_SOURCE_COLOR
// PSYS_PART_BF_ONE_MINUS_DEST_COLOR
// PSYS_PART_BF_ONE_MINUS_SOURCE_COLOR
// PSYS_PART_BF_SOURCE_ALPHA
// PSYS_PART_BF_ONE_MINUS_SOURCE_ALPHA
integer bf_dest = PSYS_PART_BF_ONE_MINUS_SOURCE_ALPHA;

list blending = [
    PSYS_PART_BLEND_FUNC_SOURCE, bf_source,
    PSYS_PART_BLEND_FUNC_DEST, bf_dest
];

Particle flow rules

float duration_system;
float duration_particle;
float burst_sleep;
integer burst_particle_count;

list flow = [
    PSYS_SRC_MAX_AGE, duration_system,
    PSYS_PART_MAX_AGE, duration_particle,
    PSYS_SRC_BURST_RATE, burst_sleep,
    PSYS_SRC_BURST_PART_COUNT, burst_particle_count
];

Particle motion rules

vector acceleration;
vector omega;
float speed_min;
float speed_max;

list motion = [
    PSYS_SRC_ACCEL, acceleration,
    PSYS_SRC_OMEGA, omega,
    PSYS_SRC_BURST_SPEED_MIN, speed_min,
    PSYS_SRC_BURST_SPEED_MAX, speed_max
];

Template script

This particle system script includes all of the rules available for particle systems. To create a specific particle effect, modify the script by removing unneeded rules in createParticleSystem() and adding values to variables.

list createParticleSystem() {
    list behavior = [ 
        PSYS_PART_FLAGS, (
            // Comment unused masks
            PSYS_PART_BOUNCE_MASK |
            PSYS_PART_EMISSIVE_MASK |
            PSYS_PART_FOLLOW_SRC_MASK |
            PSYS_PART_FOLLOW_VELOCITY_MASK |
            PSYS_PART_INTERP_COLOR_MASK |
            PSYS_PART_INTERP_SCALE_MASK |
            PSYS_PART_RIBBON_MASK |
            PSYS_PART_TARGET_LINEAR_MASK |
            PSYS_PART_TARGET_POS_MASK |
            PSYS_PART_WIND_MASK
        )
    ];

    float radius;
    float angle_begin;
    float angle_end;
    key target;

    // Pick only one pattern below:
    // PSYS_SRC_PATTERN_DROP
    // PSYS_SRC_PATTERN_EXPLODE
    // PSYS_SRC_PATTERN_ANGLE_CONE
    // PSYS_SRC_PATTERN_ANGLE
    // PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY
    integer pattern = PSYS_SRC_PATTERN_DROP;

    list presentation = [
        PSYS_PART_TARGET_LINEAR_MASK, pattern,
        PSYS_SRC_BURST_RADIUS, radius,
        PSYS_SRC_ANGLE_BEGIN, angle_begin,
        PSYS_SRC_ANGLE_END, angle_end,
        PSYS_SRC_TARGET_KEY, target
    ];

    vector color_start;
    vector color_end;
    float alpha_start;
    float alpha_end;
    vector scale_start;
    vector scale_end;
    string texture;
    float glow_start;
    float glow_end;

    list appearance = [
        PSYS_PART_START_COLOR, color_start,
        PSYS_PART_END_COLOR, color_end,
        PSYS_PART_START_ALPHA, alpha_start,
        PSYS_PART_END_ALPHA, alpha_end,
        PSYS_PART_START_SCALE, scale_start,
        PSYS_PART_END_SCALE, scale_end,
        PSYS_SRC_TEXTURE, texture,
        PSYS_PART_START_GLOW, glow_start,
        PSYS_PART_END_GLOW, glow_end
    ];

    // Pick only one of the blend functions below:
    // PSYS_PART_BF_ONE
    // PSYS_PART_BF_ZERO
    // PSYS_PART_BF_DEST_COLOR
    // PSYS_PART_BF_SOURCE_COLOR
    // PSYS_PART_BF_ONE_MINUS_DEST_COLOR
    // PSYS_PART_BF_ONE_MINUS_SOURCE_COLOR
    // PSYS_PART_BF_SOURCE_ALPHA
    // PSYS_PART_BF_ONE_MINUS_SOURCE_ALPHA
    integer bf_source = PSYS_PART_BF_SOURCE_ALPHA;

    // Pick only one of the blend functions below:
    // PSYS_PART_BF_ONE
    // PSYS_PART_BF_ZERO
    // PSYS_PART_BF_DEST_COLOR
    // PSYS_PART_BF_SOURCE_COLOR
    // PSYS_PART_BF_ONE_MINUS_DEST_COLOR
    // PSYS_PART_BF_ONE_MINUS_SOURCE_COLOR
    // PSYS_PART_BF_SOURCE_ALPHA
    // PSYS_PART_BF_ONE_MINUS_SOURCE_ALPHA
    integer bf_dest = PSYS_PART_BF_ONE_MINUS_SOURCE_ALPHA;

    list blending = [
        PSYS_PART_BLEND_FUNC_SOURCE, bf_source,
        PSYS_PART_BLEND_FUNC_DEST, bf_dest
    ];

    float duration_system;
    float duration_particle;
    float burst_sleep;
    integer burst_particle_count;

    list flow = [
        PSYS_SRC_MAX_AGE, duration_system,
        PSYS_PART_MAX_AGE, duration_particle,
        PSYS_SRC_BURST_RATE, burst_sleep,
        PSYS_SRC_BURST_PART_COUNT, burst_particle_count
    ];

    vector acceleration;
    vector omega;
    float speed_min;
    float speed_max;

    list motion = [
        PSYS_SRC_ACCEL, acceleration,
        PSYS_SRC_OMEGA, omega,
        PSYS_SRC_BURST_SPEED_MIN, speed_min,
        PSYS_SRC_BURST_SPEED_MAX, speed_max
    ];

    return 
        behavior +
        lslsentation +
        appearance +
        blending +
        flow +
        motion;
}

default
{
    state_entry()
    {
        llParticleSystem(createParticleSystem());
    }
}

PSYS_PART_FLAGS

PSYS_PART_FLAGS, integer mask

The mask value may be specified as a decimal or hex integer, or by performing the bitwise OR operation on one or more of the following flag constants:

PSYS_PART_BOUNCE_MASK

When set, specifies particles will bounce off a plane at the region Z height of the emitter. On "bounce", each particle reverses its Z-velocity. Particles spawned below the plane will reflect to an equivalent distance above the plane.

PSYS_PART_EMISSIVE_MASK

When set, particles are full-bright and are unaffected by global lighting. Otherwise, particles will be lit depending on the current global lighting conditions. Note that point lights do illuminate non-emissive particles.

PSYS_PART_FOLLOW_SRC_MASK

When set, particles move relative to the position of the emitter. Otherwise, particle position and movement are unaffected by the position/movement of the emitter. This flag disables the PSYS_SRC_BURST_RADIUS rule.

PSYS_PART_FOLLOW_VELOCITY_MASK

When set, particles rotate to orient their "top" towards the direction of movement or emission. Otherwise, particles are oriented vertically as their textures would appear (top of texture at top, left at left).

PSYS_PART_INTERP_COLOR_MASK

When set, particle color transitions from PSYS_PART_START_COLOR to PSYS_PART_END_COLOR and alpha from PSYS_PART_START_ALPHA to PSYS_PART_END_ALPHA during the particle's lifetime. The transition is a smooth interpolation.

PSYS_PART_INTERP_SCALE_MASK

When set, particle size/scale transitions from its PSYS_PART_START_SCALE setting to its PSYS_PART_END_SCALE setting during the particle's lifetime.

PSYS_PART_RIBBON_MASK

Joins a stream of particles together into a continuous strip. Particle textures are stretched (or squeezed) to join their right edges to their predecessor's left. Ribbon 'width' is controlled by the 'x' values of start and end scale. The 'y' values are used only for computing the maximum visibility distance of the particles, and the distance between particles controls the 'length' of each ribbon segment instead. Unlike other particle effects, ribbon segments are not rendered facing the viewer's camera. The Z axis of each new particle mimics the Z axis of the emitter prim. Ribbon segments will not render if they have no 'length' - this happens when particles move only 'up' or 'down' the local Z-axis of their emitter prim. PSYS_PART_FOLLOW_VELOCITY_MASK has no effect on ribbons. For a simple ribbon effect, try using the DROP pattern, TEXTURE_BLANK, ACCEL and/or WIND.

PSYS_PART_TARGET_LINEAR_MASK

When set, emitted particles move in a straight evenly-spaced line towards the target specified by the PSYS_SRC_TARGET_KEY rule. This option ignores all Non-DROP patterns and their dependent attributes (radius, burst speeds, angles, and omega). PSYS_SRC_ACCEL and PSYS_PART_WIND_MASK are ignored as well. Using PSYS_PART_BOUNCE_MASK while the target is 'below' the emitter will cause the linear particle stream to deflect upwards, terminating above the target.

PSYS_PART_TARGET_POS_MASK

When set, emitted particles change course during their lifetime, attempting to move towards the target specified by the PSYS_SRC_TARGET_KEY rule by the time they expire. Note that if no target is specified, the target moves out of range, or an invalid target is specified, the particles target the prim itself.

PSYS_PART_WIND_MASK

When set, particle movement is affected by the wind. It is applied as a secondary force on the particles.

PSYS_SRC_PATTERN

PSYS_SRC_PATTERN, integer pattern

Specifies the general emission pattern. Pattern can be one of the following values:

PSYS_SRC_PATTERN_EXPLODE

Sprays particles outwards in a spherical area. The Initial velocity of each particle is determined by PSYS_SRC_BURST_SPEED_MIN and PSYS_SRC_BURST_SPEED_MAX. The EXPLODE pattern ignores the ANGLE parameters.

PSYS_SRC_PATTERN_ANGLE_CONE

Sprays particles outwards in a spherical, sub-spherical, conical or ring shaped area, as defined by the ANGLE parameters PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END. The ANGLE_CONE pattern can be used to imitate the EXPLODE pattern by explicitly setting PSYS_SRC_ANGLE_BEGIN to 0.00000 and PSYS_SRC_ANGLE_END to 3.14159 (or PI) (or vice versa).

PSYS_SRC_PATTERN_ANGLE

Sprays particles outward in a flat circular, semi-circular, arc or ray shaped areas, as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END. The circular pattern radiates outwards around the prim's local X axis line.

PSYS_SRC_PATTERN_DROP

Creates particles with no initial velocity. The DROP pattern will override any values given for PSYS_SRC_BURST_RADIUS, PSYS_SRC_BURST_SPEED_MIN, and PSYS_SRC_BURST_SPEED_MAX, setting each to 0.00000. (All patterns will behave like the DROP pattern, if RADIUS, SPEED_MIN and SPEED_MAX are explicitly set to 0.0000.)

PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY

(incomplete implementation) acts the same as the PSYS_SRC_PATTERN_DROP pattern, it is believed that the original intention for this pattern was to invert the effect of the ANGLE parameters, making them delineate an area where particles were NOT to be sprayed. (effectively the inverse or opposite of the behavior of the ANGLE_CONE pattern).

PSYS_PART_BLEND_FUNC_SOURCE

PSYS_PART_BLEND_FUNC_SOURCE, integer bf_source

Specifies how blending function uses the incoming particle's color and alpha information to produce the rendered result. Defaults to PSYS_PART_BF_SOURCE_ALPHA. Blending function can be one of the following values:

PSYS_PART_BF_ONE

Do not scale the source or destination RGBA values.

PSYS_PART_BF_ZERO

Zero out the source or destination RGBA values.

PSYS_PART_BF_DEST_COLOR

Scale the RGBA values by the RGBA values of the destination.

PSYS_PART_BF_SOURCE_COLOR

Scale the RGBA values by the RGBA values of the particle source.

PSYS_PART_BF_ONE_MINUS_DEST_COLOR

Scale the RGBA values by the inverted RGBA values of the destination.

PSYS_PART_BF_ONE_MINUS_SOURCE_COLOR

Scale the RGBA values by the inverted RGBA values of the particle source.

PSYS_PART_BF_SOURCE_ALPHA

Scale the RGBA values by the alpha values of the particle source.

PSYS_PART_BF_ONE_MINUS_SOURCE_ALPHA

Scale the RGBA values by the inverted alpha values of the particle source.

PSYS_PART_BLEND_FUNC_DEST

PSYS_PART_BLEND_FUNC_DEST, integer bf_dest

Specifies how blending function uses the current framebuffer's color and alpha information to produce the rendered result. Defaults to PSYS_PART_BF_ONE_MINUS_SOURCE_ALPHA. To make particles blend with the background in a less opaque and more luminescent way use PSYS_PART_BF_ONE for dest and the default for source. The available blending functions are the same as those used for PSYS_PART_BLEND_FUNC_SOURCE.