Difference between revisions of "LlParticleSystem"

Revision as of 13:44, 28 January 2007

LSL Portal

Either 'func_desc' or 'return_type' & 'return_text' must be defined

(Please use 'return_text' & 'return_type' or 'func_desc' to summarize the functions actions.)

Function: llParticleSystem( list rules );


0.0	Forced Delay
10.0	Energy

• list

rules

–

Particle system rules list in the format [ rule1, data1, rule2, data2 . . . rulen, datan ]

Defines a particle system for the containing prim based on a list of rules.

Specification

Defines a particle system that sets the state of the particle emitter within the prim which the script is contained. Any other scripts in the same prim which call this function will modify the state of the same particle emitter. As such, the particle system defined by this function is a prim property, just like its size, shape, color, et cetera. Each prim has only one (1) particle emitter, located at its geometric center, and aligned along the prim's local Z-axis, pointing in the positive Z direction.

This is the only function which alters the state of the prim's particle emitter; thus, if you wish to change the emitter to a different state (i.e., emitting a different particle system entirely, or shut off the emitter completely), just call this same function with the parameters of the new particle system you wish to render instead. Specifying an empty list (i.e., llParticleSystem([]); ) turns the emitter off.

Particles are essentially 2D "sprites" and are always rendered facing the client.

The rule / data values are defined below.

Caveats

Due to a bug/limitation in the implementation of the particle system, any alpha change defined by setting PSYS_PART_END_ALPHA and the PSYS_PART_INTERP_COLOR_MASK flag always goes from a higher alpha value to a lower one. In other words, particles can only "fade-out" and can never "fade-in". This is true even if you specify it in the list where PSYS_PART_START_ALPHA is less than PSYS_PART_END_ALPHA, as the values will be re-ordered internally when the particle system is rendered.
When using particle systems that have a non-zero emitter age (PSYS_SRC_EMITTER_AGE) setting, you may notice that the particle system may restart without any scripted trigger going off. This is due to a bug which causes the emitter to "reset" when any of the prim properties are updated or otherwise sent to the viewer. As a result, you may have to use a timer or a forced sleep and then clear the particle system once the age has expired.
The spin defined by PSYS_SRC_OMEGA is relative to the global coordinate system, NOT the prim's local coordinate system.
Particles moving towards a humanoid avatar, specified by PSYS_SRC_TARGET_KEY rule and setting the PSYS_PART_TARGET_POS_MASK flag, will end up at the geometric center of the avatar's bounding box which, unfortunately, make them appear to be striking the person in the groin area. If you want them to end up at another point on a target avatar, you instead have to place a target prim that is moved to the position where you wish them to end up, and use the key of that prim for the value of the PSYS_SRC_TARGET_KEY rule.
The Second Life viewer uses optimizations in culling objects which are too small to see at certain distances. If your emitter is very small, and is culled due to distance, the particle system associated with it will not be rendered either.

Examples

Useful Snippets

Useful functions for storing/retrieving color and alpha values to/from integers:
integer ColorAlphatoRGBA(vector color, float alpha) { return ((llFloor(alpha * 255.0) & 0xFF) << 24)


Notes



The default particle count for the client is normally set at 4096. That is the max particle count the client will render for ALL active particle systems within view range. Good particle system design is key to avoid "spamming" everyone with your particles, and starving out other people's particle systems. As such, if you are experiencing trouble getting your particle emitter to emit as many particles as you like, it may be the victim of particle starvation. Client/viewer lag (low frame rates) can also cause this issue, as particles are a rather low priority for rendering. The best solution for this is to move to a less laggy environment relatively free of other particle systems when designing and testing your own.
Once particles are emitted, their direction of motion can only be affected by PSYS_PART_ACCEL, the PSYS_PART_TARGET_POS_MASK flag, or the PSYS_PART_FOLLOW_SRC_MASK flag. As such, there is no good way to create the "swirling vortex" effect (like the one used in the viewer to indicate an object talking, begin derezzed, or when an avatar leaves the sim/grid).


Deep Notes




Signature



function void llParticleSystem( list rules );






Rule / Value Constant

Type

Description

Value


System Behavior


PSYS_PART_FLAGS
integer
Various flags controlling the behavior of the particle system. The value may be specified as an integer in decimal or hex format, or by ORing together (using the | operator) one or more of the following flag constants:
0


V
a
l
u
e
s
PSYS_PART_BOUNCE_MASK
When set, specifies particles will bounce off a plane at the global Z height of the emitter. On "bounce", each particle reverses velocity and angle. This only works for particles above the plane falling down on it.
0x004


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


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.
0x010


PSYS_PART_FOLLOW_VELOCITY_MASK
When set, particles rotate to orient their "top" towards the direction of movement or emission. Otherwise, particles are always emitted based on the current rotation of the emitter.
0x020


PSYS_PART_INTERP_COLOR_MASK
When set, particle color and alpha transition from their START settings to their END settings during the particle's lifetime. The transition is a smooth interpolation.
0x001


PSYS_PART_INTERP_SCALE_MASK
When set, particle size/scale transitions from its START setting to its END setting during the particle's lifetime.
0x002


PSYS_PART_TARGET_LINEAR_MASK
(not officially documented) When set, emitted particles move in a straight line towards the target specified by the PSYS_SRC_TARGET_KEY rule. In this mode, PSYS_SRC_ACCEL, PSYS_SRC_BURST_RADIUS, and possibly other rules are ignored.
0x080


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.
0x040


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


PSYS_PART_RANDOM_ACCEL_MASK
(unimplemented) Presumed to be used to apply random acceleration to the particles.
-


PSYS_PART_RANDOM_VEL_MASK
(unimplemented) Presumed to be used to specify random velocity for the particles upon emission.
-


PSYS_PART_TRAIL_MASK
(unimplemented) Presumed to be used for implementing "trails" via emitting more particles at shorter bursts.
-


System Presentation


PSYS_SRC_PATTERN
integer
Specifies the general emission pattern.
9


V
a
l
u
e
s
PSYS_SRC_PATTERN_ANGLE
Present particles in a 2-dimensional circular section as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END. The orientation of the particle plane is at X=0 relative to the emitter's global rotation.
0x04


PSYS_SRC_PATTERN_ANGLE_CONE
Present particles in a 3-dimensional spherical section, as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END.
0x08


PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY
(not officially documented; appears to be non-functional) Present particles in a 3-dimensional spherical section, as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END, but inversely compared to the ANGLE_CONE pattern (i.e., where there were voids in ANGLE_CONE, there are particles in ANGLE_CONE_EMPTY, and vice-versa.
0x10


PSYS_SRC_PATTERN_DROP
Present particles by dropping them at the emitter position with no force. Ignores the PSYS_SRC_BURST_RADIUS, PSYS_SRC_BURST_SPEED_MIN, and PSYS_SRC_BURST_SPEED_MAX rules.
0x01


PSYS_SRC_PATTERN_EXPLODE
Present particles by shooting them out in all directions according to the burst motion rules.
0x02


PSYS_SRC_BURST_RADIUS
float
Specifies the distance from the emitter where particles will be created. This rule is ignored when the PSYS_PART_FOLLOW_SRC_MASK flag is set.
16


PSYS_SRC_ANGLE_BEGIN
float
Specifies a half angle, in radians, of a circular or spherical "dimple" or conic section (starting from the emitter facing) within which particles will NOT be emitted. Valid values are the same as for PSYS_PART_ANGLE_END, though the effects are reversed accordingly. If the pattern is PSYS_SRC_PATTERN_ANGLE, the presentation is a 2D flat circular section. If PSYS_SRC_PATTERN_ANGLE_CONE or PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY is used, the presentation is a 3D spherical section. Note that the value of this parameter and PSYS_PART_ANGLE_END are internally re-ordered such that this parameter gets the smaller of the two values.
22


PSYS_SRC_ANGLE_END
float
Specifies a half angle, in radians, of a circular or spherical "dimple" or conic section (starting from the emitter facing) within which particles will NOT be emitted. Valid values are 0.0, which will result in particles being emitted in a straight line in the direction of the emitter facing, to PI, which will result in particles being emitted in a full circular or spherical arc around the emitter, not including the "dimple" or conic section defined by PSYS_PART_ANGLE_BEGIN. If the pattern is PSYS_SRC_PATTERN_ANGLE, the presentation is a 2D flat circular section. If PSYS_SRC_PATTERN_ANGLE_CONE or PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY is used, the presentation is a 3D spherical section. Note that the value of this parameter and PSYS_PART_ANGLE_BEGIN are internally re-ordered such that this parameter gets the larger of the two values.
23


PSYS_SRC_INNERANGLE
float
DEPRECATED: Use PSYS_PART_ANGLE_BEGIN instead. Works similar to its replacement rule, except the edge of the section is aligned with the emitter facing, rather than its center.
10


PSYS_SRC_OUTERANGLE
float
DEPRECATED: Use PSYS_PART_ANGLE_END instead. Works similar to its replacement rule, except the edge of the section is aligned with the emitter facing, rather than the section's center.
11


PSYS_SRC_TARGET_KEY
key
Specifies the key of a target object, prim, or agent towarads which the particles will change course and move. They will attempt to end up at the geometric center of the target at the end of their lifetime. Requires the PSYS_PART_TARGET_POS_MASK flag be set. caveat 4
20


Particle Appearance


PSYS_PART_START_COLOR
vector
A unit vector specifying the color of the particles upon emission.
1


PSYS_PART_END_COLOR
vector
A unit vector specifying the color the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_COLOR_MASK flag is set.
3


PSYS_PART_START_ALPHA
float
Specifies the alpha of the particles upon emission. Valid values are in the range 0.0 to 1.0. Higher values are more opaque; lower ones are more transparent.
2


PSYS_PART_END_ALPHA
float
Specifies the alpha the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_COLOR_MASK flag is set. Valid values are the same as PSYS_PART_START_ALPHA. (caveat 1)
4


PSYS_PART_START_SCALE
vector
Specifies the scale or size of the particles upon emission. Valid values for each direction are 0.04 (0.03125) to 4.0, in meters. Since particles are essentially 2D sprites, the Z component of the vector is ignored and can be set to 0.0.
5


PSYS_PART_END_SCALE
vector
Specifies the scale or size the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_SCALE_MASK flag is set. Valid values are the same as PSYS_PART_START_SCALE.
6


PSYS_SRC_TEXTURE
string
Specifies the name of a texture in the prim's inventory to use for each particle. Alternatively, you may specify an asset key UUID for a texture.
12


Particle Flow


PSYS_SRC_AGE
float
Specifies the length of time, in seconds, that the emitter will operate upon coming into view range (if the particle system is already set) or upon execution of this function (if already in view range). Maximum is 60.0 seconds. Upon expiration, no more particles will be emitted, except as specified above. (caveat 2)
19


PSYS_PART_AGE
float
Specifies the lifetime of each particle emitted, in seconds. Maximum is 30.0 seconds. During this time, the particle will appear, change appearance and move according to the parameters specified in the other sections, and then disappear.
7


PSYS_SRC_BURST_RATE
float
Specifies the time interval, in seconds, between "bursts" of particles being emitted. Specifying a value of 0.0 will cause the emission of particles as fast as the viewer can do so.
13


PSYS_SRC_BURST_COUNT
integer
Specifies the number of particles emitted in each "burst".
15


Particle Motion


PSYS_SRC_ACCEL
vector
Specifies a directional acceleration vector applied to each particle as it is emitted, in meters per second. Valid values are 0.0 to 100.0 for each direction, as global coordinates.
8


PSYS_SRC_OMEGA
vector
Specifies the rotational spin of the emitter in radians per second along each axis. This "unsticks" the emitter facing from the prim's positive Z axis and is noticeable in directional presentations. Prim spin (via llTargetOmega) has no effect on emitter spin. (caveat 3)
21


PSYS_SRC_BURST_SPEED_MIN
float
Specifies the minimum value of a random range of values which is selected for each particle in a burst as its initial speed upon emission, in meters per second. Note that the value of this parameter and PSYS_PART_BURST_SPEED_MAX are internally re-ordered such that this parameter gets the smaller of the two values.
17


PSYS_SRC_BURST_SPEED_MAX
float
Specifies the maximum value of a random range of values which is selected for each particle in a burst as its initial speed upon emission, in meters per second. Note that the value of this parameter and PSYS_PART_BURST_SPEED_MIN are internally re-ordered such that this parameter gets the larger of the two values.
18

@@ Line 1: / Line 1: @@
-I'll be uploading a large block page here shortly. Edits are likely futile. [[User:Talarus Luan|Talarus Luan]] 13:43, 26 January 2007 (PST)
+{{LSL_Function|func_id=229|func_sleep=0.0|func_energy=10.0|func=llParticleSystem
-{{LSLFunctionAll|func_id=229|func_sleep=0.0|func_energy=10.0|func=llParticleSystem|p1_type=list|p1_name=rules|func_footnote=Creates a particle system based on rules. Empty list removes particle system from object.<br />List format is [ rule1, data1, rule2, data2 . . . rulen, datan ]|return_text|spec|caveats|examples|helpers|related|also|notes}}[[Category:LSL_Functions]][[Category:LSL_Stub]]
+|p1_type=list|p1_name=rules|p1_desc=Particle system rules list in the format [ rule1, data1, rule2, data2 . . . rulen, datan ]
+|func_footnote=Defines a particle system for the containing prim based on a list of rules.
+|return_text
+|spec=
+Defines a particle system that sets the state of the {{LSLG|particle emitter}} within the {{LSLG|primitive|prim}} which the {{LSLG|script}} is contained. Any other scripts in the same prim which call this function will modify the state of the same particle emitter. As such, the particle system defined by this function is a {{LSLG|primitive property|prim property}}, just like its size, shape, color, et cetera.
+Each prim has only '''one (1)''' particle emitter, located at its {{LSLG|geometric center}}, and aligned along the prim's local Z-axis, pointing in the positive Z direction.
+This is the only function which alters the state of the prim's particle emitter; thus, if you wish to change the emitter to a different state (i.e., emitting a different particle system entirely, or shut off the emitter completely), just call this same function with the parameters of the new particle system you wish to render instead. Specifying an empty list (i.e., llParticleSystem([]); ) turns the emitter off.
+Particles are essentially 2D "sprites" and are always rendered facing the client.
+The  rule / data values are defined below.
+|caveats=
+# Due to a bug/limitation in the implementation of the particle system, any alpha change defined by setting PSYS_PART_END_ALPHA and the PSYS_PART_INTERP_COLOR_MASK flag '''always''' goes from a higher alpha value to a lower one. In other words, particles can only "fade-out" and can never "fade-in". This is true even if you specify it in the list where PSYS_PART_START_ALPHA is less than PSYS_PART_END_ALPHA, as the values will be re-ordered internally when the particle system is rendered.
+# When using particle systems that have a non-zero emitter age (PSYS_SRC_EMITTER_AGE) setting, you may notice that the particle system may restart without any scripted trigger going off. This is due to a bug which causes the emitter to "reset" when any of the prim properties are updated or otherwise sent to the viewer. As a result, you may have to use a {{LSLG|timer}} or a forced {{LSLG|llSleep|sleep}} and then clear the particle system once the age has expired.
+# The spin defined by PSYS_SRC_OMEGA is relative to the global coordinate system, NOT the prim's local coordinate system.
+# Particles moving towards a humanoid avatar, specified by PSYS_SRC_TARGET_KEY rule and setting the PSYS_PART_TARGET_POS_MASK flag, will end up at the geometric center of the avatar's bounding box which, unfortunately, make them appear to be striking the person in the groin area. If you want them to end up at another point on a target avatar, you instead have to place a target prim that is moved to the position where you wish them to end up, and use the key of that prim for the value of the PSYS_SRC_TARGET_KEY rule.
+# The Second Life viewer uses optimizations in culling objects which are too small to see at certain distances. If your emitter is very small, and is culled due to distance, the particle system associated with it will not be rendered either.
+|examples
+|helpers=
+'''Useful functions for storing/retrieving color and alpha values to/from integers:'''<br />
+<code>
+integer ColorAlphatoRGBA(vector color, float alpha) {
+	return ((llFloor(alpha * 255.0) & 0xFF) << 24) |
+		((llFloor(color.x * 255.0) & 0xFF) << 16) |
+		((llFloor(color.y * 255.0) & 0xFF) << 8) |
+		(llFloor(color.z * 255.0) & 0xFF);
+}
+vector RGBAtoColor(integer rgba) {
+	return < (float)((rgba >> 16) & 0xFF) / 255.0, (float)((rgba >> 8) & 0xFF) / 255.0, (float)(rgba & 0xFF) / 255.0 >;
+}
+float RGBAtoAlpha(integer rgba) {
+	return (float)((rgba >> 24) & 0xFF) / 255.0;
+}
+</code>
+|related
+|also
+|sort=ParticleSystem
+|return_text=none
+|notes=
+* The default particle count for the client is normally set at 4096. That is the max particle count the client will render for ALL active particle systems within view range. Good particle system design is key to avoid "spamming" everyone with your particles, and starving out other people's particle systems. As such, if you are experiencing trouble getting your particle emitter to emit as many particles as you like, it may be the victim of particle starvation. Client/viewer lag (low frame rates) can also cause this issue, as particles are a rather low priority for rendering. The best solution for this is to move to a less laggy environment relatively free of other particle systems when designing and testing your own.
+* Once particles are emitted, their direction of motion can only be affected by PSYS_PART_ACCEL, the PSYS_PART_TARGET_POS_MASK flag, or the PSYS_PART_FOLLOW_SRC_MASK flag. As such, there is no good way to create the "swirling vortex" effect (like the one used in the viewer to indicate an object talking, begin derezzed, or when an avatar leaves the sim/grid).
+}}
+{| {{prettytable}}
+|{{Hl2}}|
+|{{Hl2}}| Rule / Value Constant
+|{{Hl2}}| Type
+|{{Hl2}}| Description
+|{{Hl2}}| Value
+|- style="background-color:#ccffcc;"
+| colspan="5" align="left"|'''System Behavior'''
+|-
+|colspan="2"|PSYS_PART_FLAGS||{{LSLG|integer}}||Various flags controlling the behavior of the particle system. The value may be specified as an integer in decimal or {{LSLG|hexadecimal|hex}} format, or by ORing together (using the <nowiki>|</nowiki> operator) one or more of the following flag constants:||align="center"|0
+|- style="background-color:#e0e0e0;"
+|rowspan="12" style="background-color:#c0c0c0;" align="center" valign="center"|'''V<br />a<br />l<br />u<br />e<br />s'''||colspan="2"|PSYS_PART_BOUNCE_MASK||When set, specifies particles will bounce off a plane at the global Z height of the emitter. On "bounce", each particle reverses velocity and angle. This only works for particles above the plane falling down on it.||align="center"|0x004
+|- style="background-color:#e0e0e0;"
+| colspan="2"|PSYS_PART_EMISSIVE_MASK||When set, particles are full-bright and are unaffected by global lighting (sunlight). Otherwise, particles will be lit depending on the current global lighting conditions. Note that point lights '''do''' illuminate non-emissive particles.||align="center"|0x100
+|- style="background-color:#e0e0e0;"
+| colspan="2"|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.||align="center"|0x010
+|- style="background-color:#e0e0e0;"
+| colspan="2"|PSYS_PART_FOLLOW_VELOCITY_MASK||When set, particles rotate to orient their "top" towards the direction of movement or emission. Otherwise, particles are always emitted based on the current rotation of the emitter.||align="center"|0x020
+|- style="background-color:#e0e0e0;"
+| colspan="2"|PSYS_PART_INTERP_COLOR_MASK||When set, particle color and alpha transition from their START settings to their END settings during the particle's lifetime. The transition is a smooth interpolation.||align="center"|0x001
+|- style="background-color:#e0e0e0;"
+| colspan="2"|PSYS_PART_INTERP_SCALE_MASK||When set, particle size/scale transitions from its START setting to its END setting during the particle's lifetime.||align="center"|0x002
+|- style="background-color:#e0e0e0;"
+| colspan="2"|PSYS_PART_TARGET_LINEAR_MASK||(''not officially documented'') When set, emitted particles move in a straight line towards the target specified by the PSYS_SRC_TARGET_KEY rule. In this mode, PSYS_SRC_ACCEL, PSYS_SRC_BURST_RADIUS, and possibly other rules are ignored.||align="center"|0x080
+|- style="background-color:#e0e0e0;"
+| colspan="2"|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.||align="center"|0x040
+|- style="background-color:#e0e0e0;"
+| colspan="2"|PSYS_PART_WIND_MASK||When set, particle movement is affected by the {{LSLG|llWind|wind}}. It is applied as a secondary force on the particles.||align="center"|0x008
+|- style="background-color:#e0e0e0;"
+| colspan="2"|PSYS_PART_RANDOM_ACCEL_MASK||(''unimplemented'') Presumed to be used to apply random acceleration to the particles.||align="center"| -
+|- style="background-color:#e0e0e0;"
+| colspan="2"|PSYS_PART_RANDOM_VEL_MASK||(''unimplemented'') Presumed to be used to specify random velocity for the particles upon emission.||align="center"| -
+|- style="background-color:#e0e0e0;"
+| colspan="2"|PSYS_PART_TRAIL_MASK||(''unimplemented'') Presumed to be used for implementing "trails" via emitting more particles at shorter bursts.||align="center"| -
+|- style="background-color:#ccffcc;"
+| colspan="5" align="left"|'''System Presentation'''
+|-
+| colspan="2"|PSYS_SRC_PATTERN||{{LSLG|integer}}||Specifies the general emission pattern.||align="center"|9
+|- style="background-color:#e0e0e0;"
+|rowspan="5" style="background-color:#c0c0c0;" align="center" valign="center"|'''V<br />a<br />l<br />u<br />e<br />s'''|| colspan="2"|PSYS_SRC_PATTERN_ANGLE||Present particles in a 2-dimensional circular section as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END. The orientation of the particle plane is at X=0 relative to the emitter's global rotation.||align="center"|0x04
+|- style="background-color:#e0e0e0;"
+|colspan="2"|PSYS_SRC_PATTERN_ANGLE_CONE||Present particles in a 3-dimensional spherical section, as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END.||align="center"|0x08
+|- style="background-color:#e0e0e0;"
+|colspan="2"|PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY||(''not officially documented; appears to be non-functional'') Present particles in a 3-dimensional spherical section, as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END, but inversely compared to the ANGLE_CONE pattern (i.e., where there were voids in ANGLE_CONE, there are particles in ANGLE_CONE_EMPTY, and vice-versa.||align="center"|0x10
+|- style="background-color:#e0e0e0;"
+|colspan="2"|PSYS_SRC_PATTERN_DROP||Present particles by dropping them at the emitter position with no force. Ignores the PSYS_SRC_BURST_RADIUS, PSYS_SRC_BURST_SPEED_MIN, and PSYS_SRC_BURST_SPEED_MAX rules.||align="center"|0x01
+|- style="background-color:#e0e0e0;"
+|colspan="2"|PSYS_SRC_PATTERN_EXPLODE||Present particles by shooting them out in all directions according to the burst motion rules.||align="center"|0x02
+|-
+|colspan="2"|PSYS_SRC_BURST_RADIUS||{{LSLG|float}}||Specifies the distance from the emitter where particles will be created. This rule is ignored when the PSYS_PART_FOLLOW_SRC_MASK flag is set.||align="center"|16
+|-
+|colspan="2"|PSYS_SRC_ANGLE_BEGIN||{{LSLG|float}}||Specifies a half angle, in radians, of a circular or spherical "dimple" or conic section (starting from the emitter facing) within which particles will NOT be emitted. Valid values are the same as for PSYS_PART_ANGLE_END, though the effects are reversed accordingly. If the pattern is PSYS_SRC_PATTERN_ANGLE, the presentation is a 2D flat circular section. If PSYS_SRC_PATTERN_ANGLE_CONE or PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY is used, the presentation is a 3D spherical section. Note that the value of this parameter and PSYS_PART_ANGLE_END are internally re-ordered such that this parameter gets the smaller of the two values.||align="center"|22
+|-
+|colspan="2"|PSYS_SRC_ANGLE_END||{{LSLG|float}}||Specifies a half angle, in radians, of a circular or spherical "dimple" or conic section (starting from the emitter facing) within which particles will NOT be emitted. Valid values are 0.0, which will result in particles being emitted in a straight line in the direction of the emitter facing, to PI, which will result in particles being emitted in a full circular or spherical arc around the emitter, not including the "dimple" or conic section defined by PSYS_PART_ANGLE_BEGIN. If the pattern is PSYS_SRC_PATTERN_ANGLE, the presentation is a 2D flat circular section. If PSYS_SRC_PATTERN_ANGLE_CONE or PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY is used, the presentation is a 3D spherical section. Note that the value of this parameter and PSYS_PART_ANGLE_BEGIN are internally re-ordered such that this parameter gets the larger of the two values.||align="center"|23
+|-
+|colspan="2"|<del>PSYS_SRC_INNERANGLE</del>||{{LSLG|float}}||'''DEPRECATED: Use PSYS_PART_ANGLE_BEGIN instead.''' Works similar to its replacement rule, except the edge of the section is aligned with the emitter facing, rather than its center.||align="center"|10
+|-
+|colspan="2"|<del>PSYS_SRC_OUTERANGLE</del>||{{LSLG|float}}||'''DEPRECATED: Use PSYS_PART_ANGLE_END instead.''' Works similar to its replacement rule, except the edge of the section is aligned with the emitter facing, rather than the section's center.||align="center"|11
+|-
+|colspan="2"|PSYS_SRC_TARGET_KEY||{{LSLG|key}}||Specifies the key of a target object, prim, or agent towarads which the particles will change course and move. They will attempt to end up at the geometric center of the target at the end of their lifetime. Requires the PSYS_PART_TARGET_POS_MASK flag be set. [[#Caveats|caveat 4]]||align="center"|20
+|- style="background-color:#ccffcc;"
+|colspan="5" align="left"|'''Particle Appearance'''
+|-
+|colspan="2"|PSYS_PART_START_COLOR||{{LSLG|vector}}||A {{LSLG|unit vector}} specifying the {{LSLG|color}} of the particles upon emission.||align="center"|1
+|-
+|colspan="2"|PSYS_PART_END_COLOR||{{LSLG|vector}}||A {{LSLG|unit vector}} specifying the {{LSLG|color}} the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_COLOR_MASK flag is set.||align="center"|3
+|-
+|colspan="2"|PSYS_PART_START_ALPHA||{{LSLG|float}}||Specifies the {{LSLG|alpha}} of the particles upon emission. Valid values are in the range 0.0 to 1.0. Higher values are more opaque; lower ones are more transparent.||align="center"|2
+|-
+|colspan="2"|PSYS_PART_END_ALPHA||{{LSLG|float}}||Specifies the {{LSLG|alpha}} the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_COLOR_MASK flag is set. Valid values are the same as PSYS_PART_START_ALPHA. ([[#Caveats|caveat 1]])||align="center"|4
+|-
+|colspan="2"|PSYS_PART_START_SCALE||{{LSLG|vector}}||Specifies the {{LSLG|scale}} or size of the particles upon emission. Valid values for each direction are 0.04 (0.03125) to 4.0, in meters. Since particles are essentially 2D sprites, the Z component of the vector is ignored and can be set to 0.0.||align="center"|5
+|-
+|colspan="2"|PSYS_PART_END_SCALE||{{LSLG|vector}}||Specifies the {{LSLG|scale}} or size the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_SCALE_MASK flag is set. Valid values are the same as PSYS_PART_START_SCALE.||align="center"|6
+|-
+|colspan="2"|PSYS_SRC_TEXTURE||{{LSLG|string}}||Specifies the name of a texture in the prim's inventory to use for each particle. Alternatively, you may specify an asset key UUID for a texture.||align="center"|12
+|- style="background-color:#ccffcc;"
+|colspan="5" align="left"|'''Particle Flow'''
+|-
+|colspan="2"|PSYS_SRC_AGE||{{LSLG|float}}||Specifies the length of time, in seconds, that the emitter will operate upon coming into view range (if the particle system is already set) or upon execution of this function (if already in view range). Maximum is 60.0 seconds. Upon expiration, no more particles will be emitted, except as specified above. ([[#Caveats|caveat 2]])||align="center"|19
+|-
+|colspan="2"|PSYS_PART_AGE||{{LSLG|float}}||Specifies the lifetime of each particle emitted, in seconds. Maximum is 30.0 seconds. During this time, the particle will appear, change appearance and move according to the parameters specified in the other sections, and then disappear.||align="center"|7
+|-
+|colspan="2"|PSYS_SRC_BURST_RATE||{{LSLG|float}}||Specifies the time interval, in seconds, between "bursts" of particles being emitted. Specifying a value of 0.0 will cause the emission of particles as fast as the viewer can do so.||align="center"|13
+|-
+|colspan="2"|PSYS_SRC_BURST_COUNT||{{LSLG|integer}}||Specifies the number of particles emitted in each "burst".||align="center"|15
+|- style="background-color:#ccffcc;"
+|colspan="5" align="left"|'''Particle Motion'''
+|-
+|colspan="2"|PSYS_SRC_ACCEL||{{LSLG|vector}}||Specifies a directional acceleration vector applied to each particle as it is emitted, in meters per second. Valid values are 0.0 to 100.0 for each direction, as global coordinates.||align="center"|8
+|-
+|colspan="2"|PSYS_SRC_OMEGA||{{LSLG|vector}}||Specifies the rotational spin of the emitter in radians per second along each axis. This "unsticks" the emitter facing from the prim's positive Z axis and is noticeable in directional presentations. Prim spin (via {{LSLG|llTargetOmega}}) has no effect on emitter spin. ([[#Caveats|caveat 3]])||align="center"|21
+|-
+|colspan="2"|PSYS_SRC_BURST_SPEED_MIN||{{LSLG|float}}||Specifies the minimum value of a random range of values which is selected for each particle in a burst as its initial speed upon emission, in meters per second. Note that the value of this parameter and PSYS_PART_BURST_SPEED_MAX are internally re-ordered such that this parameter gets the smaller of the two values.||align="center"|17
+|-
+|colspan="2"|PSYS_SRC_BURST_SPEED_MAX||{{LSLG|float}}||Specifies the maximum value of a random range of values which is selected for each particle in a burst as its initial speed upon emission, in meters per second. Note that the value of this parameter and PSYS_PART_BURST_SPEED_MIN are internally re-ordered such that this parameter gets the larger of the two values.||align="center"|18
+|}

Difference between revisions of "LlParticleSystem"

Revision as of 13:44, 28 January 2007

Contents

Summary

Specification

Caveats

Examples

Useful Snippets

Notes

Deep Notes

Signature

Navigation menu

Search

	Rule / Value Constant	Type	Description	Value
System Behavior
PSYS_PART_FLAGS		integer	Various flags controlling the behavior of the particle system. The value may be specified as an integer in decimal or hex format, or by ORing together (using the \| operator) one or more of the following flag constants:	0
V a l u e s	PSYS_PART_BOUNCE_MASK		When set, specifies particles will bounce off a plane at the global Z height of the emitter. On "bounce", each particle reverses velocity and angle. This only works for particles above the plane falling down on it.	0x004
	PSYS_PART_EMISSIVE_MASK		When set, particles are full-bright and are unaffected by global lighting (sunlight). Otherwise, particles will be lit depending on the current global lighting conditions. Note that point lights do illuminate non-emissive particles.	0x100
	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.	0x010
	PSYS_PART_FOLLOW_VELOCITY_MASK		When set, particles rotate to orient their "top" towards the direction of movement or emission. Otherwise, particles are always emitted based on the current rotation of the emitter.	0x020
	PSYS_PART_INTERP_COLOR_MASK		When set, particle color and alpha transition from their START settings to their END settings during the particle's lifetime. The transition is a smooth interpolation.	0x001
	PSYS_PART_INTERP_SCALE_MASK		When set, particle size/scale transitions from its START setting to its END setting during the particle's lifetime.	0x002
	PSYS_PART_TARGET_LINEAR_MASK		(not officially documented) When set, emitted particles move in a straight line towards the target specified by the PSYS_SRC_TARGET_KEY rule. In this mode, PSYS_SRC_ACCEL, PSYS_SRC_BURST_RADIUS, and possibly other rules are ignored.	0x080
	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.	0x040
	PSYS_PART_WIND_MASK		When set, particle movement is affected by the wind. It is applied as a secondary force on the particles.	0x008
	PSYS_PART_RANDOM_ACCEL_MASK		(unimplemented) Presumed to be used to apply random acceleration to the particles.	-
	PSYS_PART_RANDOM_VEL_MASK		(unimplemented) Presumed to be used to specify random velocity for the particles upon emission.	-
	PSYS_PART_TRAIL_MASK		(unimplemented) Presumed to be used for implementing "trails" via emitting more particles at shorter bursts.	-
System Presentation
PSYS_SRC_PATTERN		integer	Specifies the general emission pattern.	9
V a l u e s	PSYS_SRC_PATTERN_ANGLE		Present particles in a 2-dimensional circular section as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END. The orientation of the particle plane is at X=0 relative to the emitter's global rotation.	0x04
	PSYS_SRC_PATTERN_ANGLE_CONE		Present particles in a 3-dimensional spherical section, as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END.	0x08
	PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY		(not officially documented; appears to be non-functional) Present particles in a 3-dimensional spherical section, as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END, but inversely compared to the ANGLE_CONE pattern (i.e., where there were voids in ANGLE_CONE, there are particles in ANGLE_CONE_EMPTY, and vice-versa.	0x10
	PSYS_SRC_PATTERN_DROP		Present particles by dropping them at the emitter position with no force. Ignores the PSYS_SRC_BURST_RADIUS, PSYS_SRC_BURST_SPEED_MIN, and PSYS_SRC_BURST_SPEED_MAX rules.	0x01
	PSYS_SRC_PATTERN_EXPLODE		Present particles by shooting them out in all directions according to the burst motion rules.	0x02
PSYS_SRC_BURST_RADIUS		float	Specifies the distance from the emitter where particles will be created. This rule is ignored when the PSYS_PART_FOLLOW_SRC_MASK flag is set.	16
PSYS_SRC_ANGLE_BEGIN		float	Specifies a half angle, in radians, of a circular or spherical "dimple" or conic section (starting from the emitter facing) within which particles will NOT be emitted. Valid values are the same as for PSYS_PART_ANGLE_END, though the effects are reversed accordingly. If the pattern is PSYS_SRC_PATTERN_ANGLE, the presentation is a 2D flat circular section. If PSYS_SRC_PATTERN_ANGLE_CONE or PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY is used, the presentation is a 3D spherical section. Note that the value of this parameter and PSYS_PART_ANGLE_END are internally re-ordered such that this parameter gets the smaller of the two values.	22
PSYS_SRC_ANGLE_END		float	Specifies a half angle, in radians, of a circular or spherical "dimple" or conic section (starting from the emitter facing) within which particles will NOT be emitted. Valid values are 0.0, which will result in particles being emitted in a straight line in the direction of the emitter facing, to PI, which will result in particles being emitted in a full circular or spherical arc around the emitter, not including the "dimple" or conic section defined by PSYS_PART_ANGLE_BEGIN. If the pattern is PSYS_SRC_PATTERN_ANGLE, the presentation is a 2D flat circular section. If PSYS_SRC_PATTERN_ANGLE_CONE or PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY is used, the presentation is a 3D spherical section. Note that the value of this parameter and PSYS_PART_ANGLE_BEGIN are internally re-ordered such that this parameter gets the larger of the two values.	23
~~PSYS_SRC_INNERANGLE~~		float	DEPRECATED: Use PSYS_PART_ANGLE_BEGIN instead. Works similar to its replacement rule, except the edge of the section is aligned with the emitter facing, rather than its center.	10
~~PSYS_SRC_OUTERANGLE~~		float	DEPRECATED: Use PSYS_PART_ANGLE_END instead. Works similar to its replacement rule, except the edge of the section is aligned with the emitter facing, rather than the section's center.	11
PSYS_SRC_TARGET_KEY		key	Specifies the key of a target object, prim, or agent towarads which the particles will change course and move. They will attempt to end up at the geometric center of the target at the end of their lifetime. Requires the PSYS_PART_TARGET_POS_MASK flag be set. caveat 4	20
Particle Appearance
PSYS_PART_START_COLOR		vector	A unit vector specifying the color of the particles upon emission.	1
PSYS_PART_END_COLOR		vector	A unit vector specifying the color the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_COLOR_MASK flag is set.	3
PSYS_PART_START_ALPHA		float	Specifies the alpha of the particles upon emission. Valid values are in the range 0.0 to 1.0. Higher values are more opaque; lower ones are more transparent.	2
PSYS_PART_END_ALPHA		float	Specifies the alpha the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_COLOR_MASK flag is set. Valid values are the same as PSYS_PART_START_ALPHA. (caveat 1)	4
PSYS_PART_START_SCALE		vector	Specifies the scale or size of the particles upon emission. Valid values for each direction are 0.04 (0.03125) to 4.0, in meters. Since particles are essentially 2D sprites, the Z component of the vector is ignored and can be set to 0.0.	5
PSYS_PART_END_SCALE		vector	Specifies the scale or size the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_SCALE_MASK flag is set. Valid values are the same as PSYS_PART_START_SCALE.	6
PSYS_SRC_TEXTURE		string	Specifies the name of a texture in the prim's inventory to use for each particle. Alternatively, you may specify an asset key UUID for a texture.	12
Particle Flow
PSYS_SRC_AGE		float	Specifies the length of time, in seconds, that the emitter will operate upon coming into view range (if the particle system is already set) or upon execution of this function (if already in view range). Maximum is 60.0 seconds. Upon expiration, no more particles will be emitted, except as specified above. (caveat 2)	19
PSYS_PART_AGE		float	Specifies the lifetime of each particle emitted, in seconds. Maximum is 30.0 seconds. During this time, the particle will appear, change appearance and move according to the parameters specified in the other sections, and then disappear.	7
PSYS_SRC_BURST_RATE		float	Specifies the time interval, in seconds, between "bursts" of particles being emitted. Specifying a value of 0.0 will cause the emission of particles as fast as the viewer can do so.	13
PSYS_SRC_BURST_COUNT		integer	Specifies the number of particles emitted in each "burst".	15
Particle Motion
PSYS_SRC_ACCEL		vector	Specifies a directional acceleration vector applied to each particle as it is emitted, in meters per second. Valid values are 0.0 to 100.0 for each direction, as global coordinates.	8
PSYS_SRC_OMEGA		vector	Specifies the rotational spin of the emitter in radians per second along each axis. This "unsticks" the emitter facing from the prim's positive Z axis and is noticeable in directional presentations. Prim spin (via llTargetOmega) has no effect on emitter spin. (caveat 3)	21
PSYS_SRC_BURST_SPEED_MIN		float	Specifies the minimum value of a random range of values which is selected for each particle in a burst as its initial speed upon emission, in meters per second. Note that the value of this parameter and PSYS_PART_BURST_SPEED_MAX are internally re-ordered such that this parameter gets the smaller of the two values.	17
PSYS_SRC_BURST_SPEED_MAX		float	Specifies the maximum value of a random range of values which is selected for each particle in a burst as its initial speed upon emission, in meters per second. Note that the value of this parameter and PSYS_PART_BURST_SPEED_MIN are internally re-ordered such that this parameter gets the larger of the two values.	18