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.

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

The number of live particles that have been emitted by this emitter.

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.
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: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
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
Draws and updates the particle effect. For best results, call this in onCameraUpdate, onHUDDraw or onDraw.	nil

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

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.

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.
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.
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	8-digit hexadecimal colour values of the form: 0x########
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 8-digit hexadecimal colour values. 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

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.
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.
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.
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.

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.