Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

particlefx

Functions and properties for controlling particle effect component playback and shader constants.

Functions

particlefx.play(url: string | Hash | Url, emitter_state_function?: (self: unknown, id: unknown, emitter: unknown, state: unknown) => void): void

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.

// 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_<STATE>.
export default defineScript({
  init(self) {
    particlefx.play("#particlefx", (self, id, emitter, state) => {
      if (emitter === hash("exhaust") && state === particlefx.EMITTER_STATE_POSTSPAWN) {
        // exhaust is done spawning particles...
      }
    });
  },
});
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

Parameters

  • url: string | Hash | Url — the particle fx that should start playing.
  • emitter_state_function?: (self: unknown, id: unknown, emitter: unknown, state: unknown) => void — optional callback function that will be called when an emitter attached to this particlefx changes state.

particlefx.reset_constant(url: string | Hash | Url, emitter: string | Hash, constant: string | Hash): void

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.

// The following examples assume 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:
export default defineScript({
  init(self) {
    particlefx.reset_constant("#particlefx", "emitter", "tint");
  },
});
function init(self)
    particlefx.reset_constant("#particlefx", "emitter", "tint")
end

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

particlefx.set_constant(url: string | Hash | Url, emitter: string | Hash, constant: string | Hash, value: Vector4 | Matrix4): void

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.

// The following examples assume 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:
export default defineScript({
  init(self) {
    particlefx.set_constant("#particlefx", "emitter", "tint", vmath.vector4(1, 0, 0, 1));
  },
});
function init(self)
    particlefx.set_constant("#particlefx", "emitter", "tint", vmath.vector4(1, 0, 0, 1))
end

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 | Matrix4 — the value of the constant

particlefx.stop(2 overloads): void

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.

  1. (url: string | Hash | Url)

  2. (url: string | Hash | Url, options: { clear?: boolean })

    Parameters

    • url: string | Hash | Url — the particle fx that should stop playing
    • options: { clear?: boolean } — options used when stopping the particle fx
// How to stop a particle fx when a game object is deleted and immediately also
// clear any spawned particles:
export default defineScript({
  final(self) {
    particlefx.stop("#particlefx", { clear: true });
  },
});
function final(self)
    particlefx.stop("#particlefx", { clear = true })
end

Constants

particlefx.EMITTER_STATE_POSTSPAWN: number & { readonly __brand: "particlefx.EMITTER_STATE_POSTSPAWN" }

postspawn state The emitter is not spawning any particles, but has particles that are still alive.

particlefx.EMITTER_STATE_PRESPAWN: number & { readonly __brand: "particlefx.EMITTER_STATE_PRESPAWN" }

prespawn state The emitter will be in this state when it has been started but before spawning any particles. Normally the emitter is in this state for a short time, depending on if a start delay has been set for this emitter or not.

particlefx.EMITTER_STATE_SLEEPING: number & { readonly __brand: "particlefx.EMITTER_STATE_SLEEPING" }

sleeping state The emitter does not have any living particles and will not spawn any particles in this state.

particlefx.EMITTER_STATE_SPAWNING: number & { readonly __brand: "particlefx.EMITTER_STATE_SPAWNING" }

spawning state The emitter is spawning particles.

Properties

animation: Hash

The animation used during rendering by an emitter in a particle FX component. The property type is a hash and refers to a valid animation in an atlas or a tile source resource. If the animation isn't found, and error will be thrown.

image: Hash

The image used during rendering by an emitter in a particle FX component. The property type is a hash and refers to an image resource (atlas or tile source). Note: When setting the image, if the currently playing animation of the emitter isn't found in the new image, the animation will be set to the first animation found.

material: Hash

The material used during rendering by an emitter in a particle FX component. The property type is a hash and refers to a material resource.

On this page