SgParticleSystem
The Particle System class is meant for creating and controlling advanced particle effects in games. It provides a comprehensive and easy-to-use set of functions that enable developers to manage particle systems, control their behavior, and customize visual properties dynamically during runtime. The API mirrors common practices in modern particle system engines, offering extensive control over emission properties, particle lifetimes, velocities, colors, and transformations. This package integrates seamlessly with Lua environments, offering efficient management of particle effects with minimal overhead.
Inherits from
Usage
To use this class, add the following require at the top of your script:
Reference
create
Create a new particle system object in the scenegraph.
Parameters
selfoptions(table): A table of options to fill the parametersparent(SceneObject): The parent scene object to add this to
Returns
Promise: promise which will resolve to the created object
Example
-- Options can be omitted. This example shows the defaults,
-- only specify the ones you want different.
SgParticleSystem.create({
active = true,
name = "",
transform = Transform.new(),
layers = {0},
tags = {}
})
Properties
You can access these properties directly on the object or through :get("propertyName") or :set("propertyName", value) methods.
| Property | Type | Default | Description |
|---|---|---|---|
| active | Boolean | true | A Boolean attribute indicating whether the 3D object is active or not. When set to true, the object is considered active in the scene. |
| static | Boolean | false | A Boolean attribute indicating whether the 3D object is static or not. Static objects can and will never be transformed during runtime. |
| transform | Transform | Transform.new() | Specifies the transformation properties of the 3D object, including its position, rotation, and scale in the scene. |
| layers | Layers | [0] | Determines the layers the 3D object belongs to. Layers are used to organize objects in the scene for various purposes like rendering and interaction. |
| tags | Tags | [] | A list of tags associated with the 3D object. Tags are used for categorizing and identifying objects for scripting and scene management. |
| rendered | Boolean | true | Indicates if the 3D object is being rendered. |
| preview | Boolean | false | Previews the particle system by playing it in the editor. |
| showEmitterPreview | Boolean | true | Shows a preview of the particle system's emitter. |
| pause | Boolean | false | Pauses the particle system. |
| killAllParticles | Boolean | false | Kills all the alive particles in the system. |
| restart | Boolean | false | Hard restart of the particle system. It kills all particles, clean all data and reset the simulation time. |
destroy
Destroys the particle system.
getParticlesCount
Returns the number of particles in the particle system.
Returns
number: number of particles.
getPause
Returns the pause state of the particle system.
Returns
boolean: pause state.
getSpawnAmount
Returns the spawn amount.
Returns
number: number of particles to spawn.
getSpawnRate
Returns the spawn rate.
Returns
number: rate of particle spawning.
getRespawn
Sets the respawn flag for the particle system.
getEmitter
Returns the emitter parameters.
Returns
table: table containing the shape, type, size.
getDuration
Returns the duration of the particle system.
Returns
number: duration of the particle system.
getEmissionFlag
Returns the emission flag state describing whether or not the particle system is emitting new particles.
Returns
boolean: emission flag state.
getContinuousEmissionFlag
Returns the continuous emission flag state.
Returns
boolean: continuous emission flag state.
getLocalCoordsFlag
Returns the local coordinates flag state.
Returns
boolean: local coordinates flag state.
getAngularVelocity
Returns the angular velocity of the particles.
Returns
number: angular velocity of the particles.
getRotationDirection
Returns the direction the particles will rotate to.
Returns
number: rotation of particles. 1 will make the particles move clockwise, -1 anti-clockwise and 0 stand still.
getLifeDelta
Returns the life delta of the particles.
Returns
number: life delta value for particles.
getLifeDeltaRandom
Returns the random life delta of the particles.
Returns
number: random life delta value for particles.
getGravity
Returns the gravity applied to the particles.
Returns
number: gravity value affecting the particles.
getOrbitalVelocity
Returns the orbital velocity of the particles.
Returns
number: orbital velocity value.
getOrbitalDecay
Returns the orbital decay of the particles.
Returns
number: orbital decay value.
getOrbitalCenterPoint
Returns the orbital center point of the particles.
Returns
Vector3: orbital center point vector.
getOrbitalPlane
Returns the orbital plane of the particles.
Returns
Vector3: orbital plane vector.
getParticleLife
Returns the life of the particles.
Returns
number: life value of the particles.
getParticleSize
Returns the particle size.
Returns
table: table containing minSize, maxSize, and approach.
getInitialVelocity
Returns the particle initial velocity.
Returns
table: initial velocity of the particles encoded as a table for x, y, z values.
getFinalVelocity
Returns the particle final velocity.
Returns
table: final velocity of the particles encoded as a table for x, y, z values.
getFinalVelocityApproachValue
Returns the particle final velocity approach value.
Returns
number: final velocity approach value of the particles.
getTarget
Returns the target direction.
Returns
table: target direction vector.
getTargetForce
Returns the target force strength.
Returns
number: target force strength.
getTargetDeletionThreshold
Sets the target deletion threshold.
Returns
number: target delete threshold. A value of -1 will not kill particles.
getRandomVelocity
Returns the random velocity factor.
Returns
number: random velocity factor.
getNormalVelocity
Returns the velocity applied on the direction of normals on a emitter.
Returns
number: velocity factor.
getSpread
Returns the spread factor.
Returns
number: spread applied to the particles at emission.
getBBoxFlag
Returns the bounding box flag state.
Returns
boolean: bounding box flag state.
getBoundingBox
Returns the bounding box dimensions.
Returns
table: bounding box bottom left and top right corners encoded as min, max.
getParticleColor
Returns the particle color.
Returns
table: table containing r, g, b, a values.
getParticleRandomColorFactor
Returns the particle random color factor.
Returns
number: random color factor.
getEnableFinalColorFlag
Returns the final color flag for the particles. This indicates whether the final color property is enabled.
Returns
boolean: if the final color flag is enabled, false otherwise.
getFinalColor
Returns the final color of the particles.
Returns
table: table containing r, g, b, a values.
getTextureBlendingFlag
Returns the texture blending value for the particles. The value is between 0 and 1.
Returns
number: blending value.
getTextureHue
Gets the texture hue shift.
Returns
number: hue shift value for the texture.
getNoiseStrength
Sets the noise strength for the particle system.
Returns
number: noise strength value.
getNoiseFrequency
Sets the noise frequency for the particle system.
Returns
number: noise frequency value.
getNoiseOctaves
Sets the noise octaves for the particle system.
Returns
number: noise octaves value.
setEmitter
Sets the emitter parameters.
Parameters
shape(string): The shape of the emitter.type(string): The type of the emitter.config
Example
local emitterShape
local emitterType
local emitterConfig = {
size = 10,
radius = 5,
outerRadius = 8,
height = 20,
width = 15,
depth = 10,
life = 5.0,
lifeRandomness = 0.2
}
function update()
particleSystem:setEmitter(SgParticleSystem.EmissionShapes[emitterShape:getValue() + 1],
SgParticleSystem.EmissionTypes[emitterType:getValue() + 1], emitterConfig)
end
function rendergui()
gui.text("Emitter shape")
gui.combo("Emtiter shape", emitterShape, SgParticleSystem.EmissionShapes)
gui.combo("Emtiter type", emitterType, SgParticleSystem.EmissionTypes)
gui.endDialog()
end
setPause
Sets the pause state of the particle system.
Parameters
value(boolean): The pause state to set.
killAllParticles
Kills all particles in the system.
hideParticles
Hides all particles in the system.
showParticles
Shows all particles in the system.
restart
Restarts the particle system.
setRespawn
Sets the respawn flag for the particle system.
Parameters
value(boolean): The respawn flag state to set.
setSpawnAmount
Sets the spawn amount.
Parameters
value(number): The number of particles to spawn.
setSpawnRate
Sets the spawn rate.
Parameters
value(number): The rate of particle spawning.
setPrewarm
Sets the prewarm flag.
Parameters
value(boolean): The prewarm flag state to set.
setDuration
Sets the duration of the particle system.
Parameters
value(number): The duration of the particle system.
setContinuousEmissionFlag
Sets the continuous emission flag.
Parameters
value(boolean): The continuous emission flag state to set.
setLocalCoordsFlag
Sets the local coordinates flag.
Parameters
value(boolean): The local coordinates flag state to set.
emitAllParticles
Emits all particles at once.
emitNewParticles
Emits new particles.
Parameters
particleCount(number): The number of particles to emit.continuous(boolean): Whether to emit particles continuously.
setParticleLife
Sets the particle life parameters.
Parameters
lifeRandomness(number): The randomness factor for the lifespan.
setGravity
Sets the gravity for the particle system.
Parameters
value(number): The gravity value.
setOrbitalVelocity
Sets the orbital velocity.
Parameters
value(number): The orbital velocity value.
setOrbitalDecay
Sets the orbital decay.
Parameters
value(number): The orbital decay value.
setOrbitalCenterPoint
Sets the orbital center point.
Parameters
value(table): The center point coordinates for the orbital motion.
setOrbitalPlane
Sets the orbital plane.
Parameters
value(table): The orbital plane identifier.
setTarget
Sets the target direction for the particle system.
Parameters
direction(table): The target direction vector.
setTargetForce
Sets the target force strength.
Parameters
strength(number): The strength of the force towards the target.
setTargetDeletionThreshold
Sets the target deletion threshold.
Parameters
value(number): The deletion threshold value for particles targeting an object. A value of -1 will not kill particles.
setRandomVelocity
Sets the random velocity factor.
Parameters
value(number): The random velocity factor.
setInitialVelocity
Sets the initial velocity for particles.
Parameters
velocity(table): The initial velocity vector.
setFinalVelocity
Sets the final velocity parameters.
Parameters
target(table): The target velocity vector.
setFinalVelocityApproachValue
Sets the final velocity appraoch value.
Parameters
approachValue(number): The approach value of the final velocity.
setNormalVelocity
Sets the velocity applied on the direction of normals on a emitter. Used when emission type is set to normals. @see setEmitter()
Parameters
velocityFactor(number): The velocity factor.
setSpread
Sets the spread value for the particle system.
Parameters
value(number): The spread value.
setBBoxFlag
Sets the bounding box flag.
Parameters
boolean(boolean): The bounding box flag state to set.
setBoundingBox
Sets the bounding box dimensions.
Parameters
bboxMin(table): The minimum boundary of the bounding box.bboxMax(table): The maximum boundary of the bounding box.
setParticleSize
Sets the particle size.
Parameters
minSize(number): The minimum size of the particles.maxSize(number): The maximum size of the particles.approach(string): The approach to transition between sizes.
setAngularVelocity
Sets the angular velocity and direction.
Parameters
velocity(number): The angular velocity.direction(table): The direction vector for angular velocity.
setParticleRandomColorFactor
Sets the particle random color factor.
Parameters
factor(number): The random color factor.
setParticleColor
Sets the particle color.
Parameters
r(number): The red component of the color.g(number): The green component of the color.b(number): The blue component of the color.a(number): The alpha (transparency) component of the color.
setParticleFinalColor
Sets the particle final color.
Parameters
r(number): The red component of the final color.g(number): The green component of the final color.b(number): The blue component of the final color.a(number): The alpha (transparency) component of the final color.
setEnableFinalColorFlag
Sets the final color flag.
Parameters
value(boolean): The final color flag state to set.
setTextureBlendingFlag
Sets the texture blending flag.
Parameters
value(boolean): The texture blending flag state to set.
setBlendingValue
Sets the texture blending value.
Parameters
value(number): The texture blending value to set.
setTextureHue
Sets the texture hue shift.
Parameters
value(number): The hue shift value for the texture.
setSpriteSpeed
Sets the sprite animation speed.
Parameters
fps(number): The frames per second for the sprite animation.
getSpriteSpeed
Gets the sprite animation speed.
Returns
number: frames per second for the sprite animation.
setSpriteRollingWithLifeFlag
Sets the sprite rolling with life flag.
Parameters
boolean(boolean): The sprite rolling with life flag state to set.
getSpriteRollingWithLifeFlag
Gets the sprite rolling with life flag.
Returns
boolean: sprite rolling with life flag state.
setSpriteCols
Sets the number of columns in the sprite sheet.
Parameters
nCols(number): The number of columns in the sprite sheet.
getSpriteCols
Gets the number of colums in the sprite sheet.
Parameters
widthheight
Returns
number: number of columns in the sprite sheet.
setSpriteRows
Sets the number of rows in the sprite sheet.
Parameters
nRows(number): The number of rows in the sprite sheet.
getSpriteRows
Gets the number of rows in the sprite sheet.
Parameters
widthheight
Returns
number: number of rows in the sprite sheet.
setAtlasSize
Sets the atlas size for the sprites.
Parameters
width(number): The width of the sprite atlas.height(number): The height of the sprite atlas.
getAtlasSize
Gets the atlas size for the sprites.
Parameters
widthheight
Returns
table: table containing the width and height of the atlas.
setNoiseStrength
Sets the noise strength for the particle system.
Parameters
value(number): The noise strength value.
setNoiseFrequency
Sets the noise frequency for the particle system.
Parameters
value(number): The noise frequency value.
setNoiseOctaves
Sets the noise octaves for the particle system.
Parameters
value(number): The noise octaves value.
generateNoise
Renders a new noise texture to be applied to the particle system. An expensive call. Use only when required.
Examples
local SgParticleSystem = require 'engine/sceneobjects/sgparticles'
local Transform = require 'engine/math/transform'
local Quaternion = require 'engine/math/quaternion'
particleSystem = SgParticleSystem:findByName("YourParticleSystemName")
local transform = Transform.new(Vector3.new(10, 0, 0), Quaternion.new(0, 0, 0, 1), Vector3.new(25, 25, 25))
particleSystem:translate(transform)