Volume FX

Volume FX are real-time 3D volumetric effects rendered via GPU ray marching. Add fire, smoke, fog, ice, rain, and other atmospheric effects to your compositions as compositor layers.

How It Works

Volume FX layers generate a 3D RGBA texture from either a procedural preset or a VDB file, then ray-march through the volume each frame. The 4-channel texture encodes:

Channel	Purpose
R	Density
G	Temperature / Heat
B	Flame / Fuel
A	Density (for alpha compositing)

Volume Material

The material determines which shader and compositing strategy is used for rendering.

Material	Shader	Description
Auto	Legacy	Auto-detect from VDB grid contents (default)
Emissive	Emissive	Emission only — fire, lava, embers. Samples temperature channel for blackbody color ramp
Scatter	Scatter	Scattering only — smoke, fog, clouds. Uses Beer-Lambert extinction
Combined	Combined	Emission + scattering — explosions. Hot core emits, cool shell scatters

Emissive Material Properties

Property	Type	Default	Description
`temperature_scale`	f32	1.0	Blackbody intensity multiplier

Scatter Material Properties

Property	Type	Default	Description
`albedo`	[f32; 3]	[0.8, 0.82, 0.85]	Albedo color (neutral smoke gray)
`extinction`	f32	1.0	How quickly light is absorbed

Combined Material Properties

Property	Type	Default	Description
`temperature_scale`	f32	1.0	Blackbody intensity multiplier
`albedo`	[f32; 3]	[0.8, 0.82, 0.85]	Albedo color
`extinction`	f32	1.0	Extinction coefficient
`emission_threshold`	f32	0.3	Temperature cutoff: above = emission, below = scattering

Layer Properties

Volume FX layers expose these parameters on the compositor layer:

Property	Type	Default	Description
`volume_preset`	string	`"fire"`	Preset name (see VFX Presets)
`volume_density`	f32	0.8	Overall density multiplier
`volume_brightness`	f32	1.0	Brightness multiplier
`volume_speed`	f32	0.5	Animation speed
`volume_steps`	u32	32	Ray march step count (higher = better quality, slower)
`volume_material`	VolumeMaterial	Auto	Rendering material (see above)

Particle Volume Properties

Particle volumes use a GPU particle system with additional controls:

Property	Type	Default	Description
`particle_preset`	string	`"fire"`	Preset name
`particle_density`	f32	0.8	Particle spawn density
`particle_speed`	f32	0.5	Particle velocity
`particle_spread`	f32	0.3	Spread radius
`particle_turbulence`	f32	0.2	Turbulence amount
`particle_size`	f32	0.05	Individual particle size
`particle_brightness`	f32	1.0	Brightness multiplier
`particle_fade`	f32	0.5	Fade-out rate
`particle_depth`	f32	0.5	Depth extent
`particle_steps`	u32	32	Ray march steps

Lua API

-- Add a fire volume FX layer
pl.cmd("slot:add", {
  name = "Fire Effect",
  source = {
    type = "volume_fx",
    volume_preset = "fire",
    volume_density = 0.9,
    volume_brightness = 1.2,
    volume_speed = 0.6,
    volume_steps = 48,
    volume_material = { type = "combined",
      temperature_scale = 1.3,
      extinction = 0.8,
      emission_threshold = 0.25
    }
  }
})

-- Add a smoke layer with scatter material
pl.cmd("slot:add", {
  name = "Smoke",
  source = {
    type = "volume_fx",
    volume_preset = "smoke",
    volume_material = { type = "scatter",
      albedo = { 0.7, 0.72, 0.75 },
      extinction = 1.5
    }
  }
})

-- Add a particle volume
pl.cmd("slot:add", {
  name = "Ember Particles",
  source = {
    type = "particle_volume",
    particle_preset = "ember",
    particle_speed = 0.8,
    particle_turbulence = 0.4
  }
})

MIDI CC Automation

Volume FX parameters are automatable via CC mappings with the vfx. prefix:

CC Range	Parameters
`vfx.*`	Volume density, brightness, speed, etc.
`pv.*`	Particle density, speed, spread, etc.

Performance Tips

Ray march steps — 32 is a good balance. Increase to 64 for quality, decrease to 16 for performance.
Resolution — Volume FX render at canvas resolution. Lower canvas size improves performance.
Material choice — Scatter-only is cheapest; Combined is most expensive.
Multiple volumes — Each volume FX layer adds a full ray march pass. Use sparingly.

VFX Presets — Complete preset reference
Compositor — Layer system overview