Particles.lua

Download Latest Version

Particles is a library designed to create particle effects for LunaLua. There are some built-in effects, but effects can be altered or added using configurable .ini files. Particles require the use of OpenGL.

Installation

Place the file particles.lua and the folder particles into the LuaScriptsLib folder.

How to use

To enable the Particles library for a specific level, add this line to lunadll.lua:

local particles = loadAPI("particles");

This will load the Particle API. From there, you can create emitters from .ini files and draw particle effects into the scene.

Example

local particles = loadAPI("particles");
 
local effect = particles.Emitter(-199300,-200000, Misc.resolveFile("particles/p_flame_small.ini"));

function onCameraUpdate()
    effect:Draw();
end

This will create a small flame effect at coordinates (-199300,-200000) and draw it to the screen.

Full screen effects need to be attached to the camera as well:

local particles = loadAPI("particles");
 
local effect = particles.Emitter(0, 0, Misc.resolveFile("particles/p_rain.ini"));
effect:AttachToCamera(Camera.get()[1]);

function onCameraUpdate()
    effect:Draw();
end

This will create a rain effect and snap it to player 1's camera, allowing the effect to follow the screen.

Documentation

Classes

These are classes contained within this library

Emitter

A source object for particle effects. This contains the definition of a particle system.

Values

Emitter.x	The x coordinate of the emitter
Emitter.y	The y coordinate of the emitter
Emitter.enabled	Whether or not the emitter is emitting particles. If set to false, live particles will still be updated, but no more will be emitted.

Functions

Emitter:getParamDefault		paramName
Returns the default value of a parameter.	number/function/Col	string The name of the parameter to check.
Emitter:setParam		paramName	value
Sets a particle system parameter, which will apply to newly spawned particles. These values use the same syntax as the .ini files.	nil	string The name of the parameter to set.	string/number/Col/Grad/function The value to set the parameter to. If a string is passed, this will use the same syntax as the .ini files. Col objects cannot have numbers passed as arguments, but Col objects can be generated using ColFromHexRGB or ColFromHexRGBA. Gradient values will accept Grad objects or functions. Functions can be used to provide more complex behaviours than simple gradients.
Emitter:FlipX
Flips a particle effect horizontally.	nil
Emitter:FlipY
Flips a particle effect vertically.	nil
Emitter:AttachToCamera		camera	snap
Attaches a particle system to the given Camera object.	nil	Camera The camera to attach the emitter to.	boolean:optional Upon attaching, should the emitter snap to the centre of the camera, or maintain its current offset from the camera? Defaults to true.
Emitter:Attach		object	snap	flipOnDirectionChange	startDirection
Attaches a particle system to the given object.	nil	Block/Animation/Player/NPC The object to attach the emitter to.	boolean:optional Upon attaching, should the emitter snap to the centre of the object, or maintain its current offset from the object? Defaults to true.	boolean:optional Should the particle effect flip when the parent object changes direction? This only applies to NPC and Player objects. Defaults to false.	number:optional Which direction is the particle effect currently facing? 1 = right, -1 = left. Defaults to the current direction the parent is facing.
Emitter:GetOffset
Gets the offset of a particle system from its parent. If the particle system is not attached to a parent, returns 0,0.	number,number
Emitter:SetOffset		x	y
Sets the offset of a particle system from its parent.	nil	number The x offset from the parent.	number The y offset from the parent.
Emitter:Detach
Detaches a particle system from its parent.	nil
Emitter:KillParticles
Instantly destroys all particles that have been emitted from this emitter.	nil
Emitter:Destroy
Kills all particles associated with this emitter, and prevents the emitter from being used again.	nil
Emitter:setPrewarm		amount
Sets the prewarm values for the next time the emitter spawns or respawns.	nil	number The amount of prewarm to perform. This may be measured in seconds or frames, depending on the settings of the emitter.
Emitter:Count
The number of live particles that have been emitted by this emitter.	number
Emitter:Scale		scaleFactor
Resizes an emitter relative to its current size.	nil	number The scaling factor with which to resize the emitter. A scale factor of 1 will leave the emitter scale unchanged.
Emitter:Emit		amount
Instantly emits the specified number of particles from the emitter. Use this coupled with an emitter with a spawn rate of 0 to create burst effects.	nil	number The number of particles to emit.
Emitter:Draw		priority
Draws and updates the particle effect. For best results, call this in onCameraUpdate, onHUDDraw or onDraw.	nil	number:optional The priority with which to draw the particles. Read more about the LunaLua Render Priority. Defaults to 0.5.

Ribbon

A source object for ribbon trails. This contains the definition of a ribbon trail.

Values

Ribbon.x	The x coordinate of the emitter
Ribbon.y	The y coordinate of the emitter
Ribbon.enabled	Whether or not the emitter is generating a trail. If set to false, the existing trail will still be updated, but will not be generated.

Functions

Ribbon:getParamDefault		paramName
Returns the default value of a parameter.	number/function/Col	string The name of the parameter to check.
Ribbon:setParam		paramName	value
Sets a ribbon trail parameter, which will apply to newly spawned trail segments. These values use the same syntax as the .ini files.	nil	string The name of the parameter to set.	string/number/Col/Grad/function The value to set the parameter to. If a string is passed, this will use the same syntax as the .ini files. Col objects cannot have numbers passed as arguments, but Col objects can be generated using ColFromHexRGB or ColFromHexRGBA. Gradient values will accept Grad objects or functions. Functions can be used to provide more complex behaviours than simple gradients.
Ribbon:FlipX
Flips a ribbon effect horizontally.	nil
Ribbon:FlipY
Flips a ribbon effect vertically.	nil
Ribbon:AttachToCamera		camera	snap
Attaches a ribbon emitter to the given Camera object.	nil	Camera The camera to attach the emitter to.	boolean:optional Upon attaching, should the emitter snap to the centre of the camera, or maintain its current offset from the camera? Defaults to true.
Ribbon:Attach		object	snap	flipOnDirectionChange	startDirection
Attaches a ribbon emitter to the given object.	nil	Block/Animation/Player/NPC The object to attach the emitter to.	boolean:optional Upon attaching, should the emitter snap to the centre of the object, or maintain its current offset from the object? Defaults to true.	boolean:optional Should the ribbon emitter flip when the parent object changes direction? This only applies to NPC and Player objects. Defaults to false.	number:optional Which direction is the ribbon emitter currently facing? 1 = right, -1 = left. Defaults to the current direction the parent is facing.
Ribbon:GetOffset
Gets the offset of a ribbon emitter from its parent. If the emitter is not attached to a parent, returns 0,0.	number,number
Ribbon:SetOffset		x	y
Sets the offset of a ribbon emitter from its parent.	nil	number The x offset from the parent.	number The y offset from the parent.
Ribbon:Detach
Detaches a ribbon emitter from its parent.	nil
Ribbon:KillTrail
Instantly destroys the trail created by this ribbon emitter.	nil
Ribbon:Break
Splits the trail.	nil
Ribbon:Destroy
Kills the trail associated with this emitter, and prevents the emitter from being used again.	nil
Ribbon:Count
The number of live segments in the trail created by this emitter.	number
Ribbon:Scale		scaleFactor
Resizes an emitter relative to its current size.	nil	number The scaling factor with which to resize the emitter. A scale factor of 1 will leave the emitter scale unchanged.
Ribbon:Emit		amount
Instantly emits the specified number of trail segments from the emitter. This has limited use beyond very specialised applications.	nil	number The number of trail segments to emit.
Ribbon:Draw		priority
Draws and updates the ribbon trail. For best results, call this in onCameraUpdate, onHUDDraw or onDraw.	nil	number:optional The priority with which to draw the trail. Read more about the LunaLua Render Priority. Defaults to 0.5.

Col

A colour object, containing RGBA values

Values

Col.r	The red component of the colour, between 0 and 1
Col.g	The green component of the colour, between 0 and 1
Col.b	The blue component of the colour, between 0 and 1
Col.a	The alpha component of the colour, between 0 and 1

Operators

c1 + c1	Adds two colours together. Either colour can be substituted with a number to add to all channels in the colour.
v1 * v2	Multiplies two colours together. Either colour can be substituted with a number to multiply by all channels in the colour.

Grad

A gradient object, defining linear-interpolated gradients of colours or numbers

Functions

Grad:get		value
Gets the value of the gradient at the given position, between 0 and 1.	number/Col	number The value, between 0 and 1, to index into the gradient.
Grad.rget		value
Equivalent to Grad:get, but without the need for : notation.	number/Col	number The value, between 0 and 1, to index into the gradient.

PointField

A force field object that can affect the movement of particles, defined by a single point of attraction or repulsion with an effect radius and falloff

Values

PointField.x	The x coordinate of the point field
PointField.y	The y coordinate of the point field
PointField.radius	The falloff radius of the point field
PointField.strength	The effect strength of the point field

Functions

PointField:get		x	y
Gets the strength of the point field at the given world coordinates, as two force values in the x and y directions	number,number	number The x coordinate of the point to test	number The y coordinate of the point to test
PointField:addEmitter		emitter	shouldAttract
Registers an emitter to respond to this point field. Also allows the emitter to be specified as being attracted to or repulsed from the point field	nil	Emitter The emitter to register to the point field	boolean:optional Should particles from this emitter be attracted to the point field, or repulsed from it? Defaults to true
PointField:removeEmitter		emitter
Unregisters an emitter from reacting to this point field	nil	Emitter The emitter to remove from this point field

LineField

A force field object that can affect the movement of particles, defined by a line segment of attraction or repulsion with an effect radius and falloff

Values

LineField.x1	The x coordinate of the first point in the line field
LineField.y1	The y coordinate of the first point in the line field
LineField.x2	The x coordinate of the second point in the line field
LineField.y2	The y coordinate of the second point in the line field
LineField.radius	The falloff distance of the line field
LineField.strength	The effect strength of the line field

Functions

LineField:get		x	y
Gets the strength of the line field at the given world coordinates, as two force values in the x and y directions	number,number	number The x coordinate of the point to test	number The y coordinate of the point to test
LineField:addEmitter		emitter	shouldAttract
Registers an emitter to respond to this line field. Also allows the emitter to be specified as being attracted to or repulsed from the line field	nil	Emitter The emitter to register to the line field	boolean:optional Should particles from this emitter be attracted to the line field, or repulsed from it? Defaults to true
LineField:removeEmitter		emitter
Unregisters an emitter from reacting to this line field	nil	Emitter The emitter to remove from this line field

External Use Functions

These are functions you will need to use the library

Col		r	g	b	a
Creates a Col object.	Col	number The red component, between 0 and 255	number The green component, between 0 and 255	number The blue component, between 0 and 255	number:optional The alpha component, between 0 and 255. Defaults to 255.
ColFromHexRGB		value
Creates a Col object from a 6-digit hexadecimal number.	Col	number A 6-digit hexadecimal number to convert to a Col object.
ColFromHexRGBA		value
Creates a Col object from an 8-digit hexadecimal number.	Col	number An 8-digit hexadecimal number to convert to a Col object.
Grad		points	vals
Creates a Grad object.	Grad	table of number A list of points, between 0 and 1, to define the gradient.	table of number/table of Col A list of values to put in the gradient. Should be the same length as the points table.
PointField		x	y	radius	strength	falloff
Creates a PointField object.	PointField	number The x coordinate of the point field	number The y coordinate of the point field	number The falloff radius of the point field	number:optional The effect strength of the point field. Defaults to 1	Grad/function:optional The falloff function of the point field. 1 maps to the centre of the point field, 0 maps to the edge of the point field. Defaults to squared falloff.
LineField		x1	y1	x2	y2	radius	strength	falloff
Creates a LineField object.	LineField	number The x coordinate of the first point in the line field	number The y coordinate of the first point in the line field	number The x coordinate of the second point in the line field	number The y coordinate of the second point in the line field	number The falloff distance of the line field	number:optional The effect strength of the line field. Defaults to 1	Grad/function:optional The falloff function of the line field. 1 maps to a point on the line field, 0 maps to the edge of the line field. Defaults to squared falloff.
loadEmitterProperties		path
Creates a table containing a set of emitter properties, generated from a .ini file.	table	string The .ini file path to load the emitter properties from.
Emitter		x	y	source	prewarm
Creates an Emitter object.	Emitter	number The x coordinate of the emitter.	number The y coordinate of the emitter.	string/table A path to an emitter .ini configuration file, or a table of emitter properties.	number:optional The number of seconds or frames (depending on the emitter configuration) to prewarm the emitter.

Configuration Files

Documentation for the .ini configuration files that can be used by the library

Types

Type	Syntax
Number	Decimal numbers
Integer	Integer numbers
Number Range	Decimal numbers or ranges of the form: 0:0. Values for each particle will be chosen at random from between these values.
Colour	6-digit or 8-digit hexadecimal colour values of the form: 0x########. These can also be given as ranges of the form: 0x########:0x########, which will select a colour at random between the two for each particle, or as a list of the form: {0x########,0x########,0x########}, which will select a colour from the list at random for each particle.
Number Gradient	Gradient definitions of the form: {0,0,0},{0,0,0}. The first list may contain a list of numbers between 0 and 1, while the second list may contain any numbers. The lists should be the same length.
Colour Gradient	Gradient definitions of the form: {0,0,0},{0x########,0x########,0x########}. The first list may contain a list of numbers between 0 and 1, while the second list may contain 6 or 8-digit hexadecimal colour values. This only accepts individual colour values, and not ranges or lists. The lists should be the same length.
Texture Path	The filename of a texture object, with the extension. The file should be in the level folder, episode folder, LuaScriptsLib folder or SMBX root folder, or inside a particles or graphics/particles subfolder in any of those directories.
Enum Collision Mode	Any of the following strings: none, stop, bounce, kill
Enum Collision Style	Any of the following strings: coarse, fine
Enum Blend Mode	Any of the following strings: alpha, additive
Enum Space Mode	Any of the following strings: world, local
Enum Update Mode	Any of the following strings: seconds, frames

Some types are only used by Ribbon emitters. These are listed here:

Ribbon Types

Type	Syntax
Enum Ribbon Mode	Any of the following strings: continuous, disjoint
Enum Ribbon Scale Mode	Any of the following strings: center, centre, top, bottom

Values

Name	Type
rate	Number Range	The rate at which particles spawn from the emitter. Set to 0 to manually control emission using Emitter:Emit. By default, this value is 1.
lifetime	Number Range	The time each particle will exist for before disappearing. By default, this value is 1.
limit	Integer	The maximum number of live particles this emitter can manage at any one time. By default, this value is 500.
width	Number Range	The width of the emitter particles in pixels. By default this will be the width of a single frame of the given texture, or 0 if no texture is defined.
height	Number Range	The height of the emitter particles in pixels. By default this will be the height of a single frame of the given texture, or 0 if no texture is defined.
xOffset	Number Range	The X position of the particle relative to the emitter. By default, this value is 0.
yOffset	Number Range	The Y position of the particle relative to the emitter. By default, this value is 0.
radOffset	Number Range	A radial offset for the position of the particle relative to the emitter. Use this to generate circular offsets. By default, this value is 0.
texture	Texture Path	The path for the texture to use for particles produced by this emitter. If this is not defined, no texture will be used and particles will be flat coloured squares.
col	Colour	A colour to tint every particle produced by the emitter. By default, this value is 0xFFFFFFFF (white).
rotation	Number Range	The clockwise rotation of the particles produced by the emitter, in degrees. By default, this value is 0.
scale	Number Range	The uniform scale of the particles produced by the emitter. By default, this value is 1 (no scale change).
speedX	Number Range	The initial horizontal speed of particles produced by this emitter. By default, this value is 0.
speedY	Number Range	The initial vertical speed of particles produced by this emitter. By default, this value is 0.
rotSpeed	Number Range	The initial rotational speed of particles produced by this emitter. By default, this value is 0.
accelX	Number Range	The horizontal acceleration of particles produced by this emitter. By default, this value is 0.
accelY	Number Range	The vertical acceleration of particles produced by this emitter. By default, this value is 0.
targetX	Number Range	A relative target location for particles produced by this emitter. Setting this value will override other speed-related values.
targetY	Number Range	A relative target location for particles produced by this emitter. Setting this value will override other speed-related values.
framesX	Integer	The number of animation columns in the texture. Animation frames will be played one row after the other. By default, this value is 1.
framesY	Integer	The number of animation rows in the texture. Animation frames will be played one row after the other. By default, this value is 1.
frameSpeed	Number Range	The speed at which animation frames will play. Smaller numbers mean faster animation. By default, this value is 8.
despawnTime	Integer	The number of frames an off-screen particle system will take to deactivate. Set to -1 to leave a particle system active at all times. By default, this value is 180.
speedTime	Number Gradient	A gradient multiplier defining how both horizontal and vertical speed change over the lifetime of a particle.
speedXTime	Number Gradient	A gradient multiplier defining how horizontal speed changes over the lifetime of a particle.
speedYTime	Number Gradient	A gradient multiplier defining how vertical speed changes over the lifetime of a particle.
rotSpeedTime	Number Gradient	A gradient multiplier defining how rotational speed changes over the lifetime of a particle.
scaleTime	Number Gradient	A gradient multiplier defining how the size changes over the lifetime of a particle.
colTime	Colour Gradient	A gradient multiplier defining how colour and alpha change over the lifetime of a particle.
targetTime	Number Gradient	A gradient defining how position of a particle changes of the lifetime of the particle. Only applies if targetX or targetY are set.
speedScale	Number Gradient	A gradient multiplier defining how both horizontal and vertical speed change with the initial scale of a particle.
speedXScale	Number Gradient	A gradient multiplier defining how horizontal speed changes with the initial scale of a particle.
speedYScale	Number Gradient	A gradient multiplier defining how vertical speed changes with the initial scale of a particle.
rotSpeedScale	Number Gradient	A gradient multiplier defining how rotational speed changes with the initial scale of a particle.
space	Enum Space Mode	Determines how live particles react when the emitter is moved. If set to world, moving the emitter will only affect newly spawned particles. If set to local, live particles will move along with the emitter. By default, this value is world.
updateType	Enum Update Mode	Determines how particles update, and how speed, acceleration, and rate values are interpreted. If set to seconds, particles will update at the same rate regardless of framerate. Speed, acceleration, and rate values will be relative to seconds. If set to frames, particle simulations will slow down with framerate. Speed, acceleration, and rate values will be relative to frames. By default, this value is seconds.
blend	Enum Blend Mode	Determines how particles should be rendered to the screen. If set to alpha, then particles will be rendered with standard alpha blending. If set to additive, particles will be rendered with additive blending. By default, this value is alpha.
collision	Enum Collision Mode	Determines how particles collide with the environment. If set to none, no collision will occur. If set to stop, particles will lose all speed on impact with a block. If set to bounce, particles will bounce back using the bounceEnergy parameter as a multiplier. If set to kill, particles will be immediately destroyed on impact. WARNING: Using any collision mode other than none has a large performance cost, and will drastically reduce the maximum number of on-screen particles. By default, this value is none.
collisionType	Enum Collision Style	Determines how detailed block collisions should be, if the collision parameter is not none. If set to coarse, particles will collide with any block as if they were rectangular, even slopes. If set to fine, particles will collide with slopes correctly. By default, this value is fine.
bounceEnergy	Number Range	If the collision parameter is set to bounce, this value determines how much of the particle's speed it should retain after a bounce. By default, this value is 0.5.
boundLeft	Number	The horizontal offset from the collider centre defining the left side of the emitter's bounding box. Bounding boxes will be automatically calculated if these values are not defined.
boundRight	Number	The horizontal offset from the collider centre defining the right side of the emitter's bounding box. Bounding boxes will be automatically calculated if these values are not defined.
boundTop	Number	The vertical offset from the collider centre defining the top side of the emitter's bounding box. Bounding boxes will be automatically calculated if these values are not defined.
boundBottom	Number	The vertical offset from the collider centre defining the bottom side of the emitter's bounding box. Bounding boxes will be automatically calculated if these values are not defined.

Ribbon Trails use a different, smaller set of values, which are listed here:

Ribbon Values

Name	Type
rate	Number Range	The rate at which trail segments spawn from the emitter. Set to 0 to manually control emission using Ribbon:Emit. By default, this value is 1.
lifetime	Number Range	The time each trail segment will exist for before disappearing. By default, this value is 1.
width	Number Range	The width of the trail in pixels. By default this will be the width of a single frame of the given texture, or 32 if no texture is defined.
xOffset	Number Range	The X position of the trail source relative to the emitter. By default, this value is 0.
yOffset	Number Range	The Y position of the trail source relative to the emitter. By default, this value is 0.
texture	Texture Path	The path for the texture to use for the trail produced by this emitter. If this is not defined, no texture will be used and trails will be flat colours. Textures will be repeated along the trail on the horizontal axis of the texture.
col	Colour	A colour to tint the trail produced by the emitter. By default, this value is 0xFFFFFFFF (white).
speedX	Number Range	The initial horizontal speed of trail segments produced by this emitter. By default, this value is 0.
speedY	Number Range	The initial vertical speed of trail segments produced by this emitter. By default, this value is 0.
accelX	Number Range	The horizontal acceleration of trail segments produced by this emitter. By default, this value is 0.
accelY	Number Range	The vertical acceleration of trail segments produced by this emitter. By default, this value is 0.
targetX	Number Range	A relative target location for trail segments produced by this emitter. Setting this value will override other speed-related values.
targetY	Number Range	A relative target location for trail segments produced by this emitter. Setting this value will override other speed-related values.
framesX	Integer	The number of animation columns in the texture. Animation frames will be played one row after the other. By default, this value is 1.
framesY	Integer	The number of animation rows in the texture. Animation frames will be played one row after the other. By default, this value is 1.
frameSpeed	Number Range	The speed at which animation frames will play. Smaller numbers mean faster animation. By default, this value is 8.
maxAngle	Number	The maximum change in angle (in degrees) a trail can make before it "breaks" and creates a new trail. If the ribbonType is set to continuous, these trails will be connected. By default, this value is 60.
speedTime	Number Gradient	A gradient multiplier defining how both horizontal and vertical speed change over the lifetime of a trail segment.
speedXTime	Number Gradient	A gradient multiplier defining how horizontal speed changes over the lifetime of a trail segment.
speedYTime	Number Gradient	A gradient multiplier defining how vertical speed changes over the lifetime of a trail segment.
scaleTime	Number Gradient	A gradient multiplier defining how the trail width changes over the lifetime of a trail segment.
colTime	Colour Gradient	A gradient multiplier defining how colour and alpha change over the lifetime of a trail segment.
targetTime	Number Gradient	A gradient defining how position of a trail segment changes of the lifetime of the segment. Only applies if targetX or targetY are set.
scaleLength	Number Gradient	A gradient multiplier defining how the trail width changes over the length of a trail. 0 maps to the start of a trail, 1 maps to the end of a trail.
colLength	Colour Gradient	A gradient multiplier defining how colour and alpha change over the length of a trail. 0 maps to the start of a trail, 1 maps to the end of a trail.
updateType	Enum Update Mode	Determines how trail segments update, and how speed, acceleration, and rate values are interpreted. If set to seconds, trail segments will update at the same rate regardless of framerate. Speed, acceleration, and rate values will be relative to seconds. If set to frames, trail simulations will slow down with framerate. Speed, acceleration, and rate values will be relative to frames. By default, this value is seconds.
ribbonType	Enum Ribbon Mode	Determines how trail segments are connected. If adjacent trail segments are radically different, then the trail will be "broken", creating a new trail. If this value is set to continuous, these broken trails will be connected together again when they are both stable. If this value is set to disjoint, these broken trails will remain broken, leaving a gap. By default, this value is continuous.
scaleType	Enum Ribbon Scale Mode	Determines how trail segments are scaled over time with the scaleTime gradient. If set to center or centre, then trails will scale from the centre. If set to top, then the trail will scale from the top edge. If set to bottom, then the trail will scale from the bottom edge. By default, this value is centre.
blend	Enum Blend Mode	Determines how trails should be rendered to the screen. If set to alpha, then trails will be rendered with standard alpha blending. If set to additive, trails will be rendered with additive blending. By default, this value is alpha.

To assign these values, simply use the syntax:

name=value

These ini files also support simple variables, so long as the variable is defined earlier in the ini file. For example:

var=value
name=var

Is valid.

Comments can be applied using the Lua -- notation. For example:

name=value --This is a comment