Particles.lua

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

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