Skip to content

Material Effects

Pro Extension

Pro material effects animate StandardMaterial3D and ShaderMaterial properties at runtime. They work on both 3D GeometryInstance3D nodes and 2D CanvasItem nodes that use materials.

Material Effects

Available Material Targets

Effect Name Target Class What it animates
material_color GFFMaterialColorTarget A color property such as albedo_color or a shader uniform
material_alpha GFFMaterialAlphaTarget The alpha channel of a color property or a float shader uniform

Preset Effects

Preset Target Tweener Typical use
material_color Material Color color Shift a mesh’s albedo color
material_alpha Material Alpha linear Fade a 3D object in/out
material_flash Material Color flash Hit flash on an enemy

How Materials Are Handled

Pro automatically duplicates shared materials before writing to them so that other meshes using the same material are not affected.

  • For GeometryInstance3D: if material_override is empty, Pro duplicates the active surface material and assigns it to material_override.
  • For CanvasItem: Pro duplicates node.material and reassigns it.

When Restore is enabled, the original material_override or material reference is restored after the effect.

Target Properties

GFFMaterialColorTarget

var target = GFFMaterialColorTarget.new()
target.material_property = "albedo_color"   # StandardMaterial3D
target.material_property = "hit_color"      # ShaderMaterial uniform
target.target_color = Color.RED

GFFMaterialAlphaTarget

var target = GFFMaterialAlphaTarget.new()
target.material_property = "albedo_color"   # animates the alpha of albedo_color
target.target_alpha = 0.0

If the target property is a Color, the alpha channel is animated. If it is a float, the float value is animated directly.

Code Example

# Damage flash on a 3D enemy
GameFeelFlow.play("material_flash", $Enemy)

# Fade out a CanvasItem using a shader material
GameFeelFlow.play("material_alpha", $FadingPanel)

# Custom color shift
var effect = GFFEffectCommon.new()
effect.target = GFFMaterialColorTarget.new()
effect.target.material_property = "albedo_color"
effect.target.target_color = Color(0.2, 0.6, 1.0)
effect.tweener = GFFColorTweener.new()
effect.duration = 0.5

GameFeelFlow.play_effect($MeshInstance3D, effect)

ShaderMaterial Support

For ShaderMaterial, set material_property to the exact uniform name defined in your shader:

# Shader has: uniform vec4 flash_color : source_color = vec4(1.0)
var target = GFFMaterialColorTarget.new()
target.material_property = "flash_color"
target.target_color = Color.WHITE

Pro reads the current value with get_shader_parameter() and writes it back with set_shader_parameter().

Performance Notes

  • Material duplication happens once per effect playback. Avoid spawning hundreds of material effects on unique meshes in the same frame.
  • For hit flashes, prefer the material_flash preset with Restore enabled so the original material is returned after the flash.
  • If many instances need the same animated material, consider animating a shader uniform globally instead of using per-node material effects.