Why does my Godot RichTextLabel custom effect not animate?

The custom effect resource must be registered with the RichTextLabel via install_effect, and the bbcode_enabled flag must be true. The effect's bbcode property must match the tag in the text. Without all three, the tagged text renders as plain.

How do I write a custom RichTextEffect in Godot?

Create a new script extending RichTextEffect. Set @export var bbcode = 'wave' (your tag name). Implement _process_custom_fx(char_fx). Save as a Resource (.tres). Add to RichTextLabel's custom_effects array.

Why does my [wave] tag still appear as literal text?

bbcode_enabled may be false. Set it to true on the RichTextLabel. Confirm the tag name in the text matches the effect's bbcode export exactly. Spelling or casing mismatches show literal tags.

Fix: Godot RichTextLabel Effect Not Running on Tagged Text

Quick answer: Custom RichTextEffects need three things: bbcode_enabled = true on the label, the effect resource added to the label’s custom_effects array, and the script’s bbcode export matching the text tag exactly.

Here is how to fix Godot 4 custom RichTextEffects that are written but never run. The text shows literal tags like [wave]Hello[/wave] on screen. The fix is wiring the effect into the label’s custom_effects list and enabling BBCode.

The Symptom

You wrote a RichTextEffect script for a wave or shake animation. Use the tag in label text. The animation does not run; tags appear as literal characters or are stripped without effect.

What Causes This

bbcode_enabled false. Without it, BBCode tags are not parsed; they appear as plain text.

Effect not in custom_effects. The label needs an explicit reference to the effect resource.

Tag name mismatch. The script’s bbcode export must match the tag exactly. wave != Wave.

The Fix

Step 1: Write the effect.

# res://effects/wave_effect.gd
extends RichTextEffect
class_name WaveEffect

@export var bbcode := "wave"

func _process_custom_fx(char_fx):
    var amp := 10.0
    var freq := 5.0
    char_fx.offset.y = sin(char_fx.elapsed_time * freq + char_fx.relative_index * 0.3) * amp
    return true

Save as a script. In the editor, right-click the script → New Resource → pick the script class to create a .tres instance.

Step 2: Configure the RichTextLabel.

RichTextLabel:
  bbcode_enabled        = true
  custom_effects        = [WaveEffect.tres]
  text                  = "Hello [wave]world[/wave]"

The custom_effects array can hold multiple effect resources.

Step 3: Verify the tag name. The bbcode export determines the tag. bbcode = "wave" matches [wave][/wave]. Misspell either side and the tag is plain text.

Step 4: Pass parameters via tag attributes.

# In effect script
func _process_custom_fx(char_fx):
    var amp = char_fx.env.get("amp", 10.0)
    char_fx.offset.y = sin(char_fx.elapsed_time * 5) * amp
    return true

# In text
# [wave amp=20]Big wave[/wave]

Step 5: Test in editor preview. Set the label’s text and bbcode_enabled in the inspector. The preview animates the effect. If not, check the custom_effects list and tag spelling.

“bbcode_enabled, custom_effects, matching tag name. Three checks for animated text.”

Related Issues

For Tween signals, see Tween Finished Signal. For shader uniforms, see Shader Uniform Not Updating.

Effect resource. Custom_effects array. bbcode tag matches. The text dances.