Particle Object Agents


The Particle Object Agent provides an interface to the underlying plug-in API Particle System services. A Particle Object Agent instance is created using the constructor Particle(). This constructor can be used to create a new instance of a Particle database, or it can be used to acquire an existing Particle System, depending upon the arguments provided.

If a valid Layout Object Agent is provided to the constructor then a list of the Particle systems active on that object are returned. If no Particle systems are enabled for that object, then 'nil' is returned.

obj = Mesh("Cow");
part = Particle(obj) || error("No particle systems

When creating a new Particle system, you must specify the particle types and provide a list of the buffers to be created and maintained for each particle. Particle types can be one of PART_PARTICLE (single particle) or PART_TRAIL (particle with tail). As with most constants in LScript, these can also be specified using the string equivalents "particle" and "trail."

The following buffers can be allocated for each particle:

PART_POSITION                    (or "position")

PART_SIZE                            (or "size")

PART_SCALE                        (or "scale")

PART_ROTATION                   (or "rotation")

PART_VELOCITY                   (or "velocity")

PART_AGE                            (or "age")

PART_FORCE                       (or "force")

PART_PRESSURE                (or "pressure")

PART_TEMPERATURE         (or "temperature")

PART_MASS                        (or "mass")

PART_LINK                          (or "link")

PART_ID                              (or "id")

PART_ENABLE                    (or "enable")

PART_RGBA                         (or "rgba")

PART_COLLISION                 (or "collision")

Particles can exist in one of three states: PART_ALIVE, PART_DEAD, or PART_LIMBO. These values are used when reading/ writing the PART_ENABLE buffer.

Data Members

count returns the current number of particles (integer) defined in the instance.


save()writes particle-specific data during the save state. This method can be used only in the pre-defined save()script function.

load()loads particle data during the load state. This method can be used only in the pre-defined load() script function.

attach(Object Agent)
attach(Object Agent)attaches the particle instance to a Layout Object Agent so systems like HyperVoxels can access the particle data.

detach(Object Agent)
detach(Object Agent)disassociates the particle instance from its object.

reset()clears all particles from the instance.

addParticle()generates a new particle in the instance. The index value of the new particle is returned.

remParticle(index)removes the indicated particle index from the instance.

setParticle(index,bufid,value)sets the data for the specified particle buffer for the indicated particle index.

getParticle(index,bufid)retrieves the value in the specified particle buffer for the indicated particle index.


Here is the LScript equivalent of the particle SDK example. You can test it by applying it to an object, and then enabling that object in HyperVoxels:

@version 2.3
@script displace


create: id
    part = Particle("particle",@"position","size","enable",

newtime: id, frame, time

flags { return(WORLD); }

process: da
    i = part.addParticle();