Particles.lua

From PGE Wiki
Jump to: navigation, search

Attention: This page contains dead links!

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 in either your level's custom graphics folder for use in a level, along with a lunadll.lua file, or in the same directory as your .wld file along with a lunaworld.lua file for use throughout an entire episode.

How to use

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

local particles = API.load("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 = API.load("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 = API.load("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, killm
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