godot-ui-rich-text

Rich Text & BBCode

BBCode tags, meta clickable links, and RichTextEffect shaders define formatted text systems.

Available Scripts

[rich_text_rainbow_effect.gd](scripts/rich_text_rainbow_effect.gd)

Expert custom RichTextEffect that rotates colors over time.

[rich_text_glitch_effect.gd](scripts/rich_text_glitch_effect.gd)

Professional horror-style glitch effects with spatial jitter and alpha flickering.

[rich_text_typewriter_controller.gd](scripts/rich_text_typewriter_controller.gd)

Dialogue manager that parses sequential event tags ([pause], [speed]) during animations.

[rich_text_meta_dispatch.gd](scripts/rich_text_meta_dispatch.gd)

Advanced handling for multi-prefix URLs in meta-clicks (items, quests, NPCs).

[rich_text_image_scaler.gd](scripts/rich_text_image_scaler.gd)

Utility to dynamically scale [img] tags to match runtime font sizes.

[rich_text_hover_reactive.gd](scripts/rich_text_hover_reactive.gd)

Signals and logic for making text spans reactive to mouse hover (SFX/Cursors).

[rich_text_bbcode_sanitizer.gd](scripts/rich_text_bbcode_sanitizer.gd)

Security utility to prevent BBCode injection in public chat interfaces.

[rich_text_gradient_generator.gd](scripts/rich_text_gradient_generator.gd)

Generator for multi-stop linear gradients using granular character-level tagging.

[rich_text_auto_scroller.gd](scripts/rich_text_auto_scroller.gd)

Smooth vertical auto-scrolling logic for credits, news feeds, and logs.

[rich_text_syntax_highlighter.gd](scripts/rich_text_syntax_highlighter.gd)

Simple regex-based syntax highlighting pattern for code blocks in UI.

NEVER Do (Expert UI Rules)

Formatting & Rendering

• NEVER use complex BBCode in tight loops — Parsing a 10,000 character string with 500 tags every frame will tank performance. Cache your formatted strings.
• NEVER forget to register Custom Effects — Writing the script isn't enough. You MUST add the instance to RichTextLabel.custom_effects list via Inspector or install_effect().
• NEVER use absolute pixel sizes in [img] — [img width=128] fails on higher resolutions. Use rich_text_image_scaler.gd to sync with line height.

Click & Hover UX

• NEVER use [url] without visual feedback — If the text doesn't change color on hover or the cursor doesn't change, players won't know it's clickable. Use rich_text_hover_reactive.gd.
• NEVER hardcode layout logic into strings; strictly use BBCode Tables and Alignment Tags to ensure text structures remain flexible.
• NEVER animate text typewriter effects by modifying the text or bbcode string frame-by-frame; strictly use visible_ratio or visible_characters to avoid expensive parsing overhead and flickering.
• NEVER use standard bitmap fonts for large titles or dynamic UI; strictly use MSDF (Multichannel Signed Distance Field) fonts to ensure perfectly crisp outlines and scaling at any resolution.
• NEVER perform heavy logic inside meta_clicked — This signal is on the Main Thread. Use it to emit a command and handle processing asynchronously if needed.

Dialogue & Narrative

• NEVER use visible_ratio for pausing typewriter — visible_ratio is unreliable for per-character logic. Use visible_characters and explicit character indexing (rich_text_typewriter_controller.gd).
• NEVER allow unfiltered user input in Chat Labels — A user could type [img]huge_image_path[/img] or [color=transparent] to break your UI. MANDATORY: pipe every user-generated string through [rich_text_bbcode_sanitizer.gd](scripts/rich_text_bbcode_sanitizer.gd) before assigning text.

---

$RichTextLabel.bbcode_enabled = true
$RichTextLabel.text = "[b]Bold[/b] and [i]italic[/i] text"

Reveal API Decision

| Need | API | MANDATORY |

|------|-----|---------------|

| Simple fade / whole-line reveal | visible_ratio + Tween | Inline ok (see pattern below) |

| Pause / speed / event tags ([pause], [speed]) | visible_characters + indexer | [rich_text_typewriter_controller.gd](scripts/rich_text_typewriter_controller.gd) |

> NEVER use visible_ratio when you need per-character pause/speed tags.

Non-Obvious Tags & Effects

Skip cataloging [b] / [i] / [u] / [color] — see docs. Prefer these when non-obvious:

• [url=payload]…[/url] + meta_clicked — prefer [rich_text_meta_dispatch.gd](scripts/rich_text_meta_dispatch.gd)
• [img] sizing — use width_unit / height_unit + RichTextLabel.ImageUnit (see [migration-notes.md](references/migration-notes.md)); scale with [rich_text_image_scaler.gd](scripts/rich_text_image_scaler.gd)
• Custom effects — register via custom_effects / install_effect(); examples: [rich_text_rainbow_effect.gd](scripts/rich_text_rainbow_effect.gd), [rich_text_glitch_effect.gd](scripts/rich_text_glitch_effect.gd)

User-Generated Rich Text

MANDATORY: [rich_text_bbcode_sanitizer.gd](scripts/rich_text_bbcode_sanitizer.gd) on any chat, lobby, or player-typed path before RichTextLabel.text = ….

Handle Link Clicks

Prefer [rich_text_meta_dispatch.gd](scripts/rich_text_meta_dispatch.gd). Minimal hook:

func _ready() -> void:
    $RichTextLabel.meta_clicked.connect(_on_meta_clicked)

func _on_meta_clicked(meta: Variant) -> void:
    # Emit a command; do not run heavy game logic here
    pass

Expert Text Patterns

1. Rich-Text-MSDF-Outline (SDF)

Enable crisp, high-resolution outlines and scaling by enabling MSDF on font resources and using theme overrides.

# msdf_styler.gd
func _ready():
    # Crisp outlines regardless of screen scale
    label.add_theme_color_override("font_outline_color", Color.BLACK)
    label.add_theme_constant_override("outline_size", 4)

2. Animated-Text-Reveal

Simple fade — tween visible_ratio (keeps BBCode effects; no string rewrite):

func reveal_fade(label: RichTextLabel, new_text: String, duration: float) -> void:
    label.text = new_text
    label.visible_ratio = 0.0
    create_tween().tween_property(label, "visible_ratio", 1.0, duration)

Pause/speed tags — MANDATORY [rich_text_typewriter_controller.gd](scripts/rich_text_typewriter_controller.gd) using visible_characters (not visible_ratio).

3. Custom-BBCode-Effect (RichTextEffect)

Define custom visual tags (like [relic]) by extending RichTextEffect for unique gameplay-themed text animations.

# relic_effect.gd
@tool
extends RichTextEffect
var bbcode = "relic"

func _process_custom_fx(char_fx: CharFXTransform):
    # Retrieve param: [relic color=#ff00ff]
    var color = char_fx.env.get("color", Color.GOLD)
    # Apply sinusoidal floating
    char_fx.offset.y += sin(char_fx.elapsed_time * 5.0) * 2.0
    char_fx.color = color
    return true

Deep recipes (on demand)

> LLM-ignorance rule: if a general agent would not know it before reading, it lives here or in scripts/ — never delete, only move.

| Topic | Reference |

|-------|-----------|

| Tag catalog + 4.7 img units | [bbcode-tag-catalog.md](references/bbcode-tag-catalog.md) |

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• BBCode in RichTextLabel — tag syntax, built-in effects, images, and [url] meta for dialogue and formatted UI copy.
• RichTextLabel — bbcode_enabled, visible_characters / visible_ratio, meta_clicked, and custom_effects / install_effect().
• RichTextEffect — subclass contract for custom BBCode effects (bbcode id + _process_custom_fx).
• CharFXTransform — per-glyph color, offset, and env params used by rainbow/glitch/custom effects.
• Using fonts — MSDF / dynamic fonts so titles and BBCode scale crisply across resolutions.
• GUI skinning — theme color/constant overrides (outline, fonts) without baking styles into BBCode strings.
• Size and anchors — responsive dialogue boxes and log panels so rich text layouts survive resolution changes.
• GUI containers — keep buttons/icons in containers; use RichTextLabel for body text only.
• Custom mouse cursor — pointer feedback when hovering [url] / meta spans.
• Internationalizing games — tr() / CSV keys so BBCode templates stay localization-ready.
• Signals — wire meta_clicked / hover signals without stuffing game logic into the label.
• Tween — tween visible_ratio / visible_characters for typewriter reveals without re-parsing BBCode every frame.

Related Skills

Prerequisites

• godot-project-foundations — scene tree, Control basics, and resource imports before wiring RichTextLabel dialogue chrome.
• godot-ui-containers — responsive VBox/HBox/Scroll shells so rich text stays body copy, not a layout engine.
• godot-signal-architecture — typed meta/hover command signals so click handlers stay thin on the main thread.
• godot-gdscript-mastery — RegEx, @tool, and RefCounted helpers used by sanitizers, highlighters, and effect scripts.

Complements

• godot-ui-theming — theme type variations and font/outline overrides that BBCode should reference, not hardcode.
• godot-tweening — lifecycle-safe tweens for typewriter visible_ratio and auto-scroll polish.
• godot-input-handling — skip/advance and cursor changes that pair with meta hover without fighting Control focus.
• godot-dialogue-system — line runners and event tags that feed RichTextLabel typewriter controllers.
• godot-shaders-basics — when CharFX alone is not enough and you need canvas-item shaders around text panels.

Downstream / consumers

• godot-genre-visual-novel — VN dialogue boxes that depend on BBCode, visible_characters, and meta choice links.
• godot-genre-educational — lesson/copy UIs and interactive rich text that reuse sanitizers and highlighters.
• godot-genre-romance — affinity dialogue presentation that reuses typewriter and meta dispatch patterns.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.