Particle effects API documentation

Version: stable

Functions for controlling particle effect component playback and shader constants.

FUNCTION
particlefx.play()	start playing a particle FX
particlefx.reset_constant()	reset a shader constant for a particle FX component emitter
particlefx.set_constant()	set a shader constant for a particle FX component emitter
particlefx.stop()	stop playing a particle fx

CONSTANT
particlefx.EMITTER_STATE_POSTSPAWN	postspawn state
particlefx.EMITTER_STATE_PRESPAWN	prespawn state
particlefx.EMITTER_STATE_SLEEPING	sleeping state
particlefx.EMITTER_STATE_SPAWNING	spawning state

Functions

particlefx.play()

particlefx.play(url,[emitter_state_function])

Starts playing a particle FX component. Particle FX started this way need to be manually stopped through particlefx.stop(). Which particle FX to play is identified by the URL.

A particle FX will continue to emit particles even if the game object the particle FX component belonged to is deleted. You can call particlefx.stop() to stop it from emitting more particles.

PARAMETERS

url

string | hash | url the particle fx that should start playing.

[emitter_state_function]

function(self, id, emitter, state) optional callback function that will be called when an emitter attached to this particlefx changes state.

self: object The current object
id: hash The id of the particle fx component
emitter: hash The id of the emitter
state: constant the new state of the emitter:

particlefx.EMITTER_STATE_SLEEPING
particlefx.EMITTER_STATE_PRESPAWN
particlefx.EMITTER_STATE_SPAWNING
particlefx.EMITTER_STATE_POSTSPAWN

EXAMPLES

How to play a particle fx when a game object is created. The callback receives the hash of the path to the particlefx, the hash of the id of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.

local function emitter_state_change(self, id, emitter, state)
  if emitter == hash("exhaust") and state == particlefx.EMITTER_STATE_POSTSPAWN then
    -- exhaust is done spawning particles...
  end
end

function init(self)
    particlefx.play("#particlefx", emitter_state_change)
end

particlefx.reset_constant()

particlefx.reset_constant(url,emitter,constant)

Resets a shader constant for a particle FX component emitter. The constant must be defined in the material assigned to the emitter. Resetting a constant through this function implies that the value defined in the material will be used. Which particle FX to reset a constant for is identified by the URL.

PARAMETERS

`url`	string \| hash \| url the particle FX that should have a constant reset
`emitter`	string \| hash the id of the emitter
`constant`	string \| hash the name of the constant

EXAMPLES

The following examples assumes that the particle FX has id "particlefx", it contains an emitter with the id "emitter" and that the default-material in builtins is used, which defines the constant "tint". If you assign a custom material to the sprite, you can reset the constants defined there in the same manner.

How to reset the tinting of particles from an emitter:

function init(self)
    particlefx.reset_constant("#particlefx", "emitter", "tint")
end

particlefx.set_constant()

particlefx.set_constant(url,emitter,constant,value)

Sets a shader constant for a particle FX component emitter. The constant must be defined in the material assigned to the emitter. Setting a constant through this function will override the value set for that constant in the material. The value will be overridden until particlefx.reset_constant is called. Which particle FX to set a constant for is identified by the URL.

PARAMETERS

`url`	string \| hash \| url the particle FX that should have a constant set
`emitter`	string \| hash the id of the emitter
`constant`	string \| hash the name of the constant
`value`	vector4 the value of the constant

EXAMPLES

The following examples assumes that the particle FX has id "particlefx", it contains an emitter with the id "emitter" and that the default-material in builtins is used, which defines the constant "tint". If you assign a custom material to the sprite, you can reset the constants defined there in the same manner.

How to tint particles from an emitter red:

function init(self)
    particlefx.set_constant("#particlefx", "emitter", "tint", vmath.vector4(1, 0, 0, 1))
end

particlefx.stop()

particlefx.stop(url)

Stops a particle FX component from playing. Stopping a particle FX does not remove already spawned particles. Which particle FX to stop is identified by the URL.

PARAMETERS

url

string | hash | url the particle fx that should stop playing

EXAMPLES

How to stop a particle fx when a game object is deleted:

function final(self)
    particlefx.stop("#particlefx")
end

Particle effects API documentation

Functions

Constants