SgParticleSystem¶

The Particle System API is a Lua-based interface designed 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.

Reference¶

class SgParticleSystem¶

module:

create(options, parent)¶

Create a new particle system object in the scenegraph.

Parameters:¶

options (table) – A table of options to fill the parameters
parent (SceneObject) – The parent scene object to add this to

Returns:¶

a promise which will resolve to the created object

Return type:¶

Promise

fromObject(obj)¶

Create a particlesystem object from another scene object.

Parameters:¶: obj (SceneObject) – The scene object to convert

destroy()¶: Destroys the particle system.

getParticlesCount()¶

Returns the number of particles in the particle system.

Returns:¶: The number of particles.
Return type:¶: number

getPause()¶

Returns the pause state of the particle system.

Returns:¶: The pause state.
Return type:¶: boolean

getSpawnAmount()¶

Returns the spawn amount.

Returns:¶: The number of particles to spawn.
Return type:¶: number

getSpawnRate()¶

Returns the spawn rate.

Returns:¶: The rate of particle spawning.
Return type:¶: number

getRespawn(value)¶

Sets the respawn flag for the particle system.

Parameters:¶: value (boolean) – The respawn flag state to set.

getPrewarm()¶

Returns the prewarm flag state. WIP

Returns:¶: The prewarm flag state.
Return type:¶: boolean

getPrewarmAmount()¶

Returns the prewarm amount.

Returns:¶: The number of particles prewarmed.
Return type:¶: number

getEmitter()¶

Returns the emitter parameters.

Returns:¶: A table containing the shape, type, size.
Return type:¶: table

getDuration()¶

Returns the duration of the particle system.

Returns:¶: The duration of the particle system.
Return type:¶: number

getEmissionFlag()¶

Returns the emission flag state.

Returns:¶: The emission flag state.
Return type:¶: boolean

getContinuousEmissionFlag()¶

Returns the continuous emission flag state.

Returns:¶: The continuous emission flag state.
Return type:¶: boolean

getLocalCoordsFlag()¶

Returns the local coordinates flag state.

Returns:¶: The local coordinates flag state.
Return type:¶: boolean

getAngularVelocity()¶

Returns the angular velocity of the particles.

Returns:¶: The angular velocity of the particles.
Return type:¶: number

getRotationDirection()¶

Returns the direction the particles will rotate to.

anti-clockwise and 0 stand still.

Returns:¶: The rotation of particles. 1 will make the particles move clockwise, -1
Return type:¶: number

getLifeDelta()¶

Returns the life delta of the particles.

Returns:¶: The life delta value for particles.
Return type:¶: number

getLifeDeltaRandom()¶

Returns the random life delta of the particles.

Returns:¶: The random life delta value for particles.
Return type:¶: number

getGravity()¶

Returns the gravity applied to the particles.

Returns:¶: The gravity value affecting the particles.
Return type:¶: number

getOrbitalVelocity()¶

Returns the orbital velocity of the particles.

Returns:¶: The orbital velocity value.
Return type:¶: number

getOrbitalDecay()¶

Returns the orbital decay of the particles.

Returns:¶: The orbital decay value.
Return type:¶: number

getOrbitalCenterPoint()¶

Returns the orbital center point of the particles.

Returns:¶: The orbital center point vector.
Return type:¶: Vector3

getOrbitalPlane()¶

Returns the orbital plane of the particles.

Returns:¶: The orbital plane vector.
Return type:¶: Vector3

getParticleLife()¶

Returns the life of the particles.

Returns:¶: The life value of the particles.
Return type:¶: number

getParticleLife()

Returns the life of the particles.

Returns:¶: The life value of the particles.
Return type:¶: number

getParticleSize()¶

Returns the particle size.

Returns:¶: A table containing minSize, maxSize, and approach.
Return type:¶: table

getInitialVelocity()¶

Returns the particle initial velocity.

Returns:¶: The initial velocity of the particles encoded as a table for x, y, z values.
Return type:¶: table

getFinalVelocity()¶

Returns the particle final velocity.

Returns:¶: The final velocity of the particles encoded as a table for x, y, z values.
Return type:¶: table

getFinalVelocityApproachValue()¶

Returns the particle final velocity approach value.

Returns:¶: The final velocity approach value of the particles.
Return type:¶: number

getTarget()¶

Returns the target direction.

Returns:¶: The target direction vector.
Return type:¶: table

getTargetForce()¶

Returns the target force strength.

Returns:¶: The target force strength.
Return type:¶: number

getTargetDeletionThreshold()¶

Sets the target deletion threshold.

Returns:¶: The target delete threshold. A value of -1 will not kill particles.
Return type:¶: number

getRandomVelocity()¶

Returns the random velocity factor.

Returns:¶: The random velocity factor.
Return type:¶: number

getNormalVelocity()¶

Returns the velocity applied on the direction of normals on a emitter.

Returns:¶: The velocity factor.
Return type:¶: number

getSpread()¶

Returns the spread factor.

Returns:¶: The spread applied to the particles at emission.
Return type:¶: number

getBBoxFlag()¶

Returns the bounding box flag state.

Returns:¶: The bounding box flag state.
Return type:¶: boolean

getBoundingBox()¶

Returns the bounding box dimensions.

Returns:¶: The bounding box bottom left and top right corners encoded as min, max.
Return type:¶: table

getParticleColor()¶

Returns the particle color.

Returns:¶: A table containing r, g, b, a values.
Return type:¶: table

getParticleRandomColorFactor()¶

Returns the particle random color factor.

Returns:¶: The random color factor.
Return type:¶: number

getFinalColorFlag()¶

Returns the final color flag for the particles.

This indicates whether the final color property is enabled.

Returns:¶: True if the final color flag is enabled, false otherwise.
Return type:¶: boolean

getFinalColor()¶

Returns the final color of the particles.

Returns:¶: A table containing r, g, b, a values.
Return type:¶: table

getTextureBlendingFlag()¶

Returns the texture blending flag for the particles.

This indicates whether texture blending is enabled.

Returns:¶: True if texture blending is enabled, false otherwise.
Return type:¶: boolean

getTextureBlendingFlag()

Returns the texture blending value for the particles. The value is between 0 and 1.

Returns:¶: The blending value.
Return type:¶: number

getTextureHue()¶

Returns the hue of the particle’s texture.

Returns:¶: The hue value of the particle’s texture.
Return type:¶: number

getParticleFadeOverLifetimeFlag()¶

Returns the particle fade-over-lifetime flag.

This indicates whether particles fade over their lifetime.

Returns:¶: True if particles fade over their lifetime, false otherwise.
Return type:¶: boolean

getNoiseStrength()¶

Sets the noise strength for the particle system.

Returns:¶: The noise strength value.
Return type:¶: number

getNoiseFrequency()¶

Sets the noise frequency for the particle system.

Returns:¶: The noise frequency value.
Return type:¶: number

getNoiseOctaves()¶

Sets the noise octaves for the particle system.

Returns:¶: The noise octaves value.
Return type:¶: number

setEmitter(shape, type, size)¶

Sets the emitter parameters.

Parameters:¶

shape (str) – The shape of the emitter.
type (str) – The type of the emitter.
size (number) – The size of the emitter.

Usage:

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(value)¶

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(value)¶

Sets the respawn flag for the particle system.

Parameters:¶: value (boolean) – The respawn flag state to set.

setSpawnAmount(value)¶

Sets the spawn amount.

Parameters:¶: value (number) – The number of particles to spawn.

setSpawnRate(value)¶

Sets the spawn rate.

Parameters:¶: value (number) – The rate of particle spawning.

setPrewarm(value)¶

Sets the prewarm flag.

Parameters:¶: value (boolean) – The prewarm flag state to set.

setPrewarmAmount(value)¶

Sets the prewarm amount.

Parameters:¶: value (number) – The number of particles to prewarm.

runPrewarm()¶: Runs the prewarm process.

setDuration(value)¶

Sets the duration of the particle system.

Parameters:¶: value (number) – The duration of the particle system.

setEmissionFlag(value)¶

Sets the emission flag.

Parameters:¶: value (boolean) – The emission flag state to set.

setContinuousEmissionFlag(value)¶

Sets the continuous emission flag.

Parameters:¶: value (boolean) – The continuous emission flag state to set.

setLocalCoordsFlag(value)¶

Sets the local coordinates flag.

Parameters:¶: value (boolean) – The local coordinates flag state to set.

updateEmitterMatrices(object)¶

Updates the emitter matrices.

Parameters:¶: object (table) – The object containing the emitter matrices data.

updateEmitterPosition(object)¶

Updates the emitter position.

Parameters:¶: object (table) – The object containing the emitter position data.

emitAllParticles()¶: Emits all particles at once.

emitNewParticles(particleCount, continuous)¶

Emits new particles.

Parameters:¶

particleCount (number) – The number of particles to emit.
continuous (boolean) – Whether to emit particles continuously.

setParticleLife(life, lifeRandomness)¶

Sets the particle life parameters.

Parameters:¶

life (number) – The lifespan of the particles.
lifeRandomness (number) – The randomness factor for the lifespan.

setLifeDelta(value)¶

Sets the life delta.

Parameters:¶: value (number) – The life delta value.

setLifeDeltaRandom(value)¶

Sets the life delta randomness.

Parameters:¶: value (number) – The randomness factor for the life delta.

setGravity(value)¶

Sets the gravity for the particle system.

Parameters:¶: value (number) – The gravity value.

setOrbitalVelocity(value)¶

Sets the orbital velocity.

Parameters:¶: value (number) – The orbital velocity value.

setOrbitalDecay(value)¶

Sets the orbital decay.

Parameters:¶: value (number) – The orbital decay value.

setOrbitalCenterPoint(value)¶

Sets the orbital center point.

Parameters:¶: value (table) – The center point coordinates for the orbital motion.

setOrbitalPlane(value)¶

Sets the orbital plane.

Parameters:¶: value (table) – The orbital plane identifier.

setTarget(direction)¶

Sets the target direction for the particle system.

Parameters:¶: direction (table) – The target direction vector.

setTargetForce(strength)¶

Sets the target force strength.

Parameters:¶: strength (number) – The strength of the force towards the target.

setTargetDeletionThreshold(value)¶

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(value)¶

Sets the random velocity factor.

Parameters:¶: value (number) – The random velocity factor.

setInitialVelocity(velocity)¶

Sets the initial velocity for particles.

Parameters:¶: velocity (table) – The initial velocity vector.

setFinalVelocity(target)¶

Sets the final velocity parameters.

Parameters:¶: target (table) – The target velocity vector.

setFinalVelocityApproachValue(approachValue)¶

Sets the final velocity appraoch value.

Parameters:¶: approachValue (number) – The approach value of the final velocity.

setNormalVelocity(velocityFactor)¶

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(value)¶

Sets the spread value for the particle system.

Parameters:¶: value (number) – The spread value.

setBBoxFlag(boolean)¶

Sets the bounding box flag.

Parameters:¶: boolean (boolean) – The bounding box flag state to set.

setBoundingBox(bboxMin, bboxMax)¶

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(minSize, maxSize, approach)¶

Sets the particle size.

Parameters:¶

minSize (number) – The minimum size of the particles.
maxSize (number) – The maximum size of the particles.
approach (str) – The approach to transition between sizes.

setAngularVelocity(velocity, direction)¶

Sets the angular velocity and direction.

Parameters:¶

velocity (number) – The angular velocity.
direction (table) – The direction vector for angular velocity.

setParticleRandomColorFactor(factor)¶

Sets the particle random color factor.

Parameters:¶: factor (number) – The random color factor.

setParticleTexture(texture)¶

Sets the particle texture.

Parameters:¶: texture (str) – The texture identifier for the particles.

setParticleColor(r, g, b, a)¶

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(r, g, b, a)¶

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.

setFinalColorFlag(value)¶

Sets the final color flag.

Parameters:¶: value (boolean) – The final color flag state to set.

setTextureBlendingFlag(value)¶

Sets the texture blending flag.

Parameters:¶: value (boolean) – The texture blending flag state to set.

setBlendingValue(value)¶

Sets the texture blending value.

Parameters:¶: value (number) – The texture blending value to set.

setTextureHue(value)¶

Sets the texture hue shift.

Parameters:¶: value (number) – The hue shift value for the texture.

setParticleFadeOverLifetimeFlag(value)¶

Sets the particle fade over lifetime flag.

Parameters:¶: value (boolean) – The fade over lifetime flag state to set.

setSpriteSpeed(fps)¶

Sets the sprite animation speed.

Parameters:¶: fps (number) – The frames per second for the sprite animation.

setSpriteRollingWithLifeFlag(boolean)¶

Sets the sprite rolling with life flag.

Parameters:¶: boolean (boolean) – The sprite rolling with life flag state to set.

setSpriteCols(nCols)¶

Sets the number of columns in the sprite sheet.

Parameters:¶: nCols (number) – The number of columns in the sprite sheet.

setSpriteRows(nRows)¶

Sets the number of rows in the sprite sheet.

Parameters:¶: nRows (number) – The number of rows in the sprite sheet.

setAtlasSize(width, height)¶

Sets the atlas size for the sprites.

Parameters:¶

width (number) – The width of the sprite atlas.
height (number) – The height of the sprite atlas.

setNoiseStrength(value)¶

Sets the noise strength for the particle system.

Parameters:¶: value (number) – The noise strength value.

setNoiseFrequency(value)¶

Sets the noise frequency for the particle system.

Parameters:¶: value (number) – The noise frequency value.

setNoiseOctaves(value)¶

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.

Examples¶

Retrieving a particle system and translating it¶

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)