particle node

Go to: Related nodes. Attributes.

The particle node implements a particle object (a collection of particles). It uses the position, velocity, acceleration (and mass, if the user adds it) attributes to compute dynamics for the particles. It also has attributes to define goal forces for the particles and to write per-particle expressions for the particles. To save memory, many attributes are added dynamically as the user needs them: these include lifespan, color, goals, and most rendering attributes. The particle node also maintains the collection of collision events which has been defined for this object, and resolves the effect of those events as collisions occur.

Node name	Parents	Classification	MFn type	Compatible function sets
particle	deformableShape	drawdb/geometry/dynamics/particle	kParticle	kBase kNamedObject kDependencyNode kDagNode kShape kParticle

Attributes (190)

Attribute quick index omitted (too many attributes to show them all).

Long name (short name) Type Default Flags

position (pos) vectorArray empty

Runtime state, positions in object-space at the end of the time-step, per-particle. Requesting this attribute will force the dynamics to be solved.

rampPosition (rps) vectorArray empty

Use this attribute to control position by a ramp. The values from this attribute will be copied into "position" before each step in the dynamics simulation.

centroid (ctd) double3

Centroid (average position) of the particles. This is in local coordinates. See also worldCentroid.

centroidX (ctdx) double 0.0

X-component of centroid (average position) of the particles. This is in local coordinates. See also worldCentroid.

centroidY (ctdy) double 0.0

Y-component of centroid (average position) of the particles. This is in local coordinates. See also worldCentroid.

centroidZ (ctdz) double 0.0

Z-component of centroid (average position) of the particles. This is in local coordinates. See also worldCentroid.

lastPosition (lpos) vectorArray empty

The position of the particles at the end of the previous timestep. This attribute does force the evaluation of dynamics.

velocity (vel) vectorArray empty

Runtime state, velocities at the end of the time-step, per-particle.

rampVelocity (rvl) vectorArray empty

Use this attribute to control velocity with a ramp. The values from this attribute will be copied into "velocity" before each step in the dynamics simulation.

lastVelocity (lvel) vectorArray empty

The velocity at the end of the previous solving step. This will have its value set at the END of the previous solving step.

acceleration (acc) vectorArray empty

Runtime state, accelerations, per-particle.

rampAcceleration (rac) vectorArray empty

This is where all ramps input "acceleration" will actually connect. The values from this attribute will be copied into "acceleration" before each step in the dynamics simulation.

force (frc) vectorArray empty

The effects of fields, goals, etc. on the particles are accumulated in this attribute.

inputForce (ifc) vectorArray empty

This is the input multi-attribute where any fields acting on this particle object are connected. These are accumulated in the computePlug() section for aForce, along with other forces like goals.

worldPosition (wps) vectorArray empty

This is the world-space position of the particles at the end of the time-step. Requesting this attribute will force the dynamics to be solved.

worldCentroid (wctn) double3

World-space centroid (average position) of the particles. This is in world coordinates. See also "centroid."

worldCentroidX (wctx) double 0.0

X-component of world centroid (average position) of the particles. This is in world coordinates. See also "centroid."

worldCentroidY (wcty) double 0.0

Y-component of world centroid (average position)of the particles. This is in world coordinates. See also "centroid."

worldCentroidZ (wctz) double 0.0

Z-component of world centroid (average position) of the particles. This is in world coordinates. See also "centroid."

lastWorldPosition (lwps) vectorArray empty

The world-space position of the particles at the end of the previous timestep. This attribute does force the evaluation of dynamics.

worldVelocity (wvl) vectorArray empty

This is the world-space velocity of the particles at the end of the time-step. This includes motion from the parent matrix.

worldVelocityInObjectSpace (wvo) vectorArray empty

This is the world-space velocity of the particles as derived from dynamics and from motion of the world matrix. THis value is then tranformed into object-space for drawing.

lastWorldVelocity (lwvl) vectorArray empty

This is the world-space velocity from the end of the LAST time-step.

lastWorldMatrix (lwm) matrix identity

This is the world matrix from the last time evaluated (currentSceneTime - sceneTimeStepSize).

position0 (pos0) vectorArray empty

Initial state, positions, per-particle.

velocity0 (vel0) vectorArray empty

Initial state, velocities, per-particle.

acceleration0 (acc0) vectorArray empty

Initial state, accelerations, per-particle.

emitterId0 (eid0) doubleArray empty

This attribute holds the emitter id (multi index) of the particles added to this object from emitters and the emit action, but NOT from collision events.

useStartupCache (usc) bool false

This boolean attribute is used at file save and load. It records whether a runtime state has been stored in a startup cache file. If this attribute is true, Maya will use the values stored in that file instead of restoring the initial state and running up the scene. If Maya cannot find the startup cache file or it does not contain valid data, Maya will run up the scene. Users normally do not set this attribute. Instead, use the dynamics preferences window to tell Maya to do all the necessary operations. Just setting this attribute does not create the cache.

startupCachePath (scp) string NULL

This attribute holds the name of the file path on which to find the startup cache file (see useStartupCache). Users normally do not set this attribute. Maya sets it when creating the cache. The path is always relative to the workspace particle data area.

startupCacheFrame (scf) integer 0

Ifentifies the frame for which the current startup cache is valid. generally this will be the frame for which this object was most recently saved. Users notmally should not set this attribute. Use the Dynamics option window to enable or disable startup cache.

cachedPosition (cpos) vectorArray empty

This will have its value set at the END of the solving step. This attribute shares the memory with aPosition and is the most current value of aPosition WITHOUT forcing evaluation of the dynamics.

lastCachedPosition (lcps) vectorArray empty

This is the most current value for aLastPosition WITHOUT forcing evaluation of the dynamics.

cachedWorldPosition (cwps) vectorArray empty

This is the most current value for the aWorldPosition attribute WITHOUT forcing evaluation of the dynamics.

cachedWorldCentroid (cwcn) double3

Cached World-space centroid (average position) of the particles. This is the most current value of the worldCentroid WITHOUT forcing the evaluation of dynamics.

cachedWorldCentroidX (cwcx) double 0.0

Cached World x-component of centroid (average position) of the particles. This is the most current value of the worldCentroid WITHOUT forcing the evaluation of dynamics.

cachedWorldCentroidY (cwcy) double 0.0

Cached World y-component of centroid (average position) of the particles. This is the most current value of the worldCentroid WITHOUT forcing the evaluation of dynamics.

cachedWorldCentroidZ (cwcz) double 0.0

Cached World z-component of centroid (average position) of the particles. This is the most current value of the worldCentroid WITHOUT forcing the evaluation of dynamics.

cachedVelocity (cvel) vectorArray empty

This will have its value set at the END of the solving step. Its value will be that of the resulting aVelocity attribute.

cachedWorldVelocity (cwvl) vectorArray empty

This will have its value set at the END of the solving step. Its value will be that of the resulting aVelocity attribute.

count (cnt) integer 0

The number of particles in the object.

computingCount (cmp) bool false

This is a boolean used to avoid recursion in the computeCount method. It should not be set by customers.

mass (mas) doubleArray empty

Runtime state, mass, per-particle.

mass0 (mas0) doubleArray empty

Initial state, mass, per-particle.

massCache (masc) doubleArray empty

Cached state, mass.

particleId (id) doubleArray empty

Unique id number for each particle.

particleId0 (id0) doubleArray empty

Initial state, id values, per-particle.

idCache (idc) doubleArray empty

Cached state, id values.

idMapping (idm) compound n/a

This compound holds the mapping information for the particle ID values.

sortedId (sid) intArray empty

This array holds the particleId values sorted in ascending order. Together with idIndex, it can be used to locate a given id quickly in the arrays of particle data.

idIndex (idix) intArray empty

This array holds the index positions into the per-particle attribute arrays for the corresponding ids stored in aSortedId. Together with sortedId, it can be used to locate a given id quickly in the arrays of particle data.

nextId (nid) integer 0

Next available value for aId

nextId0 (nid0) integer 0

Initial value of aNextId

birthTime (bt) doubleArray empty

This stores the time, in seconds, at which each particle was born. This makes the age computation more accurate and easily calculated.

birthTime0 (bt0) doubleArray empty

Initial state, birth times, per-particle.

birthTimeCache (btc) doubleArray empty

Cached state, birth times, per-particle.

age (ag) doubleArray empty

Age per-particle in seconds.

age0 (ag0) doubleArray empty

Initial state, ages, per-particle.

ageCache (agc) doubleArray empty

Cached state, age values.

emission (emt) genericArray empty

This attribute holds all of the particles added to this object from emitters and the emit action, but NOT from collision events.

emitterId (eid) doubleArray empty

This attribute holds the emitter id (multi index) of the particles added to this object from emitters and the emit action, but NOT from collision events.

dieOnEmissionVolumeExit (dve) bool false

If the particles were emitted from a volume, die when they exit that volume.

isFull (ifl) bool false

Tells any object whether this particle object has room for any new particles or not, based on the maxCount and count attributes.

newParticles (npt) genericArray empty

This is where emitters will send any particles that they create for this particle object.

collisionEvents (cev) bool false

Requesting this attribute will trigger collision events.

death (dth) bool false

Requesting this attribute will trigger death of old particles.

lifespanMode (lfm) enum 0

Determines which attributes to use for particle lifespan. "Range" means use lifespan + lifespanRandom together to give each particle an individual lifespan. This lifespan is stored in the attribute "finalLifespanPP." "PP" means that you want to drive lifespans using the lifespanPP attribute. You must then either write an expression or set values for this attribute in the component editor. "Live forever" disables lifespan altogether. In this mode, all particles live forever, unless killed by collision events or emission volume exit (see the dieOnEmissionVolume exit attribute). Lifespan mode has nothing to do with events or emission volume exit and does not override them.

lifespanRandom (lfr) double 0.0

Used only if lifespanMode is set to "Random Range." Identifies a range of random variation for the lifespan of each particle. If set to a non-zero value, each particle's lifespan varies randomly up to plus or minus lifespanRandom/2, with the "lifespan" attribute value as the mean (the average lifespan). For example, lifespan 5 and lifespanRandom 2 will make the lifespans vary between 4 and 6. In Constant or Random Range mode, the finalLifespanPP attribute stores the values generated from lifespan and lifespanRandom. Note: Changes in the values of lifespan and lifespanRandom affect only new particles, not particles that already exist. For example, if you key the value of lifespan to be 2 up until frame 50 and 5 thereafter, then particles generated from frame 1 to 50 will have finalLifespanPP 2 and particles generated after frame 50 will have finalLifespanPP 5. The finalLifespanPP values of particles born prior to frame 50 will not change.

finalLifespanPP (flp) doubleArray empty

finalLifespanPP stores the final result of the particle object's lifespan computations, from whatever lifespan mode is currently in force. if the lifespan mode is "use lifespanPP" then this attribute will be a copy of lifespanPP. If the mode is "constant" or "random range" then it will be generated from lifespan and lifespan random. If the mode is "None" then it will be an array of maximum float values. You cannot write to finalLifespanPP, the particle object generates it for you. You can always access finalLifespanPP for expressions and it will always be the effective lifespan value regardless of mode. Note that there is no finalLifespanPP0 initial state attribute. Instead, finalLifespanPP values are re-generated when needed from the random stream.

generalSeed (gsd) integer 0

Seed for random number generation. It is independent of all other random number streams.

randState (rnst) long3

Current state of random stream. Should not be set by users.

randStateX (rstx) integer 0

Current state of random stream. Should not be set by users.

randStateY (rsty) integer 0

Current state of random stream. Should not be set by users.

randStateZ (rstz) integer 0

Current state of random stream. Should not be set by users.

expressionsAfterDynamics (ead) bool false

This boolean attribute lets the user decide whether they want the expressions to happen before or after the dynamics is computed.

executeCreationExpression (ece) bool false

This attribute is requested to trigger the execution of creation expressions.

executeRuntimeBeforeDynamicsExpression (erbe) bool false

This attribute is requested to trigger the execution of runtime expressions.

executeRuntimeAfterDynamicsExpression (erae) bool false

This attribute is requested to trigger the execution of runtime expressions.

input (xi) Generic NULL

This attribute is where any input attribute for the expressions, both runtime and creation, is connected.

output (xo) Generic NULL

This attribute is where any output attribute for the expressions, both runtime and creation, is connected.

time (tim) time 0film

This holds the value for time to be queried in seconds. This is a separate attribute then the time in frames because the Sophia (MEL) nodes are using a plug to decide which values to get. If they just had a handle to the time-in-seconds plug, we could not tell if the user wanted seconds or frames. Also, it must be a TattributeTime instead of a Double because the dependency graph would try to insert a conversion node in between the time node and this attribute. This would always result in the current time unit to be sent.

frame (frm) time 0film

This holds the value for time to be queried in frames. This is a separate attribute then the time in seconds because the Sophia (MEL) nodes are using a plug to decide which values to get. If they just had a handle to the time-in-seconds plug, we could not tell if the user wanted seconds or frames. Also, it must be a TattributeTime instead of a Double because the dependency graph would try to insert a conversion node in between the time node and this attribute. This would always result in the current time unit to be sent.

internalRuntimeExpression (irx) string NULL

This is the internal representation of the runtime expression. All of the places where attributes were are replaced with tokens representing the multi-index of the input/output attribute to which they are connected.

internalRuntimeBeforeDynamicsExpression (irbx) string NULL

internalRuntimeAfterDynamicsExpression (irax) string NULL

internalCreationExpression (icx) string NULL

This is the internal representation of the creation expression. All of the places where attributes were are replaced with tokens representing the multi-index of the input/output attribute to which they are connected.

currentParticle (xcp) integer 0

During the evaluation of both runtie and creation expressions, this value is used to keep track of which particle's value each per-particle attribute is to get/set.

diedLastTime (dlt) integer 0

OBSOLETE ATTRIBUTE. No effect.

netEmittedLastTime (nlt) integer 0

OBSOLETE ATTRIBUTE. No effect.

startEmittedIndex (sei) integer -1

OBSOLETE ATTRIBUTE. No effect.

isDynamic (isd) bool true

Toggle dynamics on/off for this object.

dynamicsWeight (dw) double 1.0

Fraction of dynamics forces which get applied each time step.

forcesInWorld (fiw) bool true

This boolean tells the solver to transform all field forces into object space before doing the dynamics. This makes the particles respond as if they were in the same space as the forces when they are in some non-identity hierarchy.

conserve (con) double 1.0

If set to a value less than one, only the corresponding portion of existing velocity will be retained when computing the next step. For example, if conserve is 0, all existing velocity will be erased before each new step. The name "conserve" refers to conservation momentum. Real (Newtonian) physics corresponds to conserve = 1.

emissionInWorld (eiw) bool true

This boolean tells the particle object to assume that particles created from emission are in world space, and to transform them into object space before adding them to the particle array. This makes the particles respond as if they were in the same space as the emitter when they are in some non-identity hierarchy.

maxCount (mxc) integer -1

Maximum count of particles this shape will allow. If some particles die off, new particles will again be accepted up to the max count, and so on.

levelOfDetail (lod) double 1

Currently only used to scale the amount of emission to be used for quick motion tests without having to change emitter values. Affects only emitted particles.

inheritFactor (inh) double 0.0

Fraction of emitter velocity that particles emitted into this object inherit.

seed (sd) integer 1

Random number stream seed for emitter's random number stream. Separate seed for each emitter. Set seeds equal to get identical stream. Resetting the seed at a particular frame will restart the stream.

fieldData (fd) compound n/a

This is the compound that holds all of the default attribute for the fields to connect to. The contents are just sharing the data from the real attributes.

fieldDataPosition (fdp) vectorArray empty

This is the default place that the fields will get this particle object's position data from. It will share the data from aPosition.

fieldDataVelocity (fdv) vectorArray empty

This is the default place that the fields will get this particle object's velcoity data from. It will share the data from aVelocity.

fieldDataMass (fdm) doubleArray empty

This is the default place that the fields will get this particle object's mass data from. It will share the data from aMass.

fieldDataDeltaTime (fdt) time 0film

This is the default place that the fields will get this particle object's timeStep size from. It will share the data from aTimeStepSize.

emitterData (ed) compound n/a

This is the compound that holds all of the default attribute for the emitters to connect to. The contents are just sharing the data from the real attributes.

emitterDataPosition (edp) vectorArray empty

This is the default place that the emitters will get this particle object's position data from. It will share the data from aPosition.

emitterDataVelocity (edv) vectorArray empty

This is the default place that the emitters will get this particle object's velcoity data from. It will share the data from aVelocity.

emitterDataDeltaTime (edt) time 0film

This is the default place that the emitters will get this particle object's timeStep size from. It will share the data from aTimeStepSize.

forceDynamics (fdn) bool false

By requesting this attribute, all of the dynamics, emission, and death will be forced for this particle shape. It is intended to be used for batch mode and dynamics run-up.

currentTime (cti) time 0film

This is the current time used for the particle solution. By default, it is given an incoming connection from the main time node. This can be replaced with some other connection (e.g. from an expression or param curve), and then the solving is done based on that time value. There must be some incoming connection in order for the particle object to play back.

currentTimeSave (cts) time 0film

This is a copy of the currentTime attribute to be saved to file in the case where the user wishes to save runtime state. Users should not set or read this attribute. Use currentTime instead.

evaluationTime (eti) time 0.0film

For internal use only.

currentSceneTime (cst) time 1.0film

This is that actual scene time. It is set from the current graph whenever aCurrentTime is set so that we can recover the worldMatrix information correctly. Users should not set this attribute.

lastTimeEvaluated (lti) time 0film

This would get the value from aCurrentTime "copied" into it at the end of the solving process. There are no AFFECTS relationships here so that requesting this attribute does not trigger any other evaluation. Because of the timing of when this attribute gets set, it should not be used by users as reliable data. It is for internal computation only.

lastSceneTime (lst) time 0film

This is the scene time for the last time the dynamics was evaluated. It is only valid at the beginning of the dynamics computation. After the dynamics computation, it is set to be the current scene time. It is used when computing the lastWorldMatrix attribute. We need to build a context with the scene time of the last evaluation.

cachedTime (chti) time 0film

Users should not set or use this attribute. Results will be unpredictable.

timeStepSize (tss) time 0film

For internal use only. Users should not set this. It is defined as (currentTime - lastTimeEvaluated)/overSamples.

sceneTimeStepSize (sts) time 0film

This is the step size in scene time. This should be used for world-space computations. Users should not set this attribute.

startFrame (stf) double 1.0

This is the frame after which dynamics will be solved. No dynamics will play back for this object prior to startFrame.

startTime (stt) time 0.0film

The time after which dynamics will be solved for this particle object. This is set from the startFrame attribute. Users should set startFrame instead of this attribute.

inputGeometry (igeo) Generic n/a

Input Geometr(y/ies) for soft body. This should be connected from the local/object-space version of the geometry. Valid inputs are polygons, nurbs surfaces, nurbs curves, and lattices.

inputGeometryPoints (igpt) vectorArray empty

This attribute stores the point data from the inputGeometry attribute as a vectorArray. This allows the expressions to have access and knowledge about the geometry.

inputGeometrySpace (igs) enum 0

This attribute tells the particle object which coordinate space to make the inputGeometryPoints attribute in. The inputGeometry is received with the points in the geometry's local space. If the attribute is set to 0(kGeomLocal), then those same point values are put into the inputGeometryPoints. If the value is 1(kGeomWorld), then the point values are transformed input world-space with the geometry's world matrix. Finally, if the value is 2(kGeomParticle), then the points are transformed into world-space with the geometry's world matrix, and then into the particle object's loca space with the particle objecty's inverse world matrix.

enforceCountFromHistory (ecfh) bool true

Tells the particle object to keep its count consistent with the pointCount of any incoming history in inputGeometry, if one exists.

targetGeometry (tgeo) Generic n/a

Geometry for soft body.

targetGeometryWorldMatrix (tgm) matrix identity

This attribute is optionally connected to from the world matrix of the target geometry. It allows the targetGeometrySpace attribute to correctly use the kTargetGeomLocal setting.

targetGeometrySpace (tgs) enum 2

This attribute tells the particle object which coordinate space to build the targetGeometry data in. If targetGeometrySpace is 2(kTargetGeomParticle), then the values from the particle object's position attribute are used as the points for the target geometry. If the value is 1(kTargetGeomWorld), then the position points are transformed into world-space with the particle object's world matrix. If the value is 0(kTargetGeomLocal), then the position points are transformed into world-space, and then they are transformed into the target geometry's local space with the inverse of targetGeometryMatrix if it has an incoming connection. If targetGeometryMatrix does not have a connection, then a warning is displayed telling the user why it can not get the target geometry's world matrix, and the identity matrix is used.

goalSmoothness (gsm) double 3

This value is used to control the "smoothness" of the change in the goal forces as the weight changes from 0.0 to 1.0. This is purely an asthetic effect, with no scientific basis. The higher the number, the smoother the change.

goalGeometry (ggeo) Generic n/a

The input geometry attributes for the goal objects.

goalWeight (gw) double 0.0

The goal weights for the various goal objects.

goalActive (ga) bool true

The active status for the goal objects. This is a switch that turns each goal ON or OFF. This has the same visual as setting the corresponding goalWeight to 0. The difference is that with a goalActive of OFF, the goal positions are not even taken into account in the computation, and therefore make the computation run faster.

goalUvSetName (guv) string NULL

For goal objects that have multiple uv sets, this attribute specifies which uv set to use when goalU/goalV values are present for particles.

cacheData (chd) bool 0

Indicates that caching is on/off.

cacheWidth (chw) integer 1

The width of the cache is the number of different time points for which the state can be cached.

collisions (col) bool false

Requesting this attribute will trigger collisions.

traceDepth (trd) integer 10

This is the maximum number of consecutive collisions that are detected within a frame for each particle. Particles may collide fewer times, of course.

collisionData (cda) compound n/a

Parent attribute for all collision input data.

collisionGeometry (cge) sweptGeometry NULL

The swept geometry for the connected shape.

collisionResilience (crs) double 0.0

How much of the particle's velocity perpendicular to the surface is reflected

collisionFriction (cfr) double 0.0

The amount of a particle's velocity parallel to a surface that is lost in the collision

collisionOffset (cof) double 0.01

The distance the particle is offset from point of intersection on surface during reflection.

collisionRecords (crc) genericArray empty

This is the READ-ONLY attribute where all of the information about the particle object's collisions for each frame is stored.

totalEventCount (tec) integer 0

Total number of collisions which have occurred for this object. All collisions are counted regardless of whether any collision events were actually executed. In other words, totalEventCount is the sum of the per-particle "event" attribute.

eventTest (evt) bool false

True if any particle collision has occured since the last time the attribute was read. However, if you read the attribute twice in succession in the same frame you will get the same result both times. Note that it does not matter whether collision events were executed at the collisions in question.

lastTotalEventCount (ltec) integer 0

Used to compute eventTest attribute.

eventSeed (esd) integer 0

Seed for random number generation for events. All events tap into the same random number stream. It is independent of all other random number streams.

eventRandState (erst) long3

Current state of random stream for events. Should not be set by users.

eventRandStateX (ersx) integer 0

Current state of random stream for events. Should not be set by users.

eventRandStateY (ersy) integer 0

Current state of random stream for events. Should not be set by users.

eventRandStateZ (ersz) integer 0

Current state of random stream for events. Should not be set by users.

eventTarget (etg) Message n/a

Target parameters of particle collision events. Edit this through the particle event editor.

eventName (evn) string NULL

Names of particle collision events. Edit this through the particle event editor.

eventValid (evv) integer -1

Marks valid particle collision events. Setting this to false turns an event off, in effect. Edit this through the particle event editor.

eventCount (ecp) short -1

Event count parameters of particle collision events. Edit this through the particle event editor.

eventEmit (eve) short -1

Emit parameters of particle collision events. Edit this through the particle event editor.

eventSplit (evs) short -1

Split parameters of particle collision events. Edit this through the particle event editor.

eventDie (evd) short -1

Die parameters of particle collision events. Edit this through the particle event editor.

eventRandom (evr) short -1

Random parameters of particle collision events. Edit this through the particle event editor.

eventSpread (esp) double -1.0

Controls random distribution of multiple particles created at single collision. Edit this through the particle event editor.

eventProc (epr) string NULL

Proc names for particle collision events. Edit this through the particle event editor.

instanceData (idt) compound n/a

This compound attribute groups together the attributes that provide data about instanced particles to the instancer node, or other node that can make use of this info.

instanceAttributeMapping (iam) stringArray NULL

This attribute defines the names of the attributes for which the instancePointData attribute will output per-particle data.

instancePointData (ipd) genericArray empty

This attribute contains per-particle data that is created according to the string data (attribute names) in the instanceAttributeMapping attribute. For each attribute listed by the instanceAttributeMapping, an array of per-particle data is output for use by the instancer node.

debugDraw (dbd) short 0

For internal use only. Should not be set by customers.

numberOfEvents (nev) short 0