godot-ui-rich-text

name	godot-ui-rich-text
description	Expert blueprint for RichTextLabel with BBCode formatting (bold, italic, colors, images, clickable links) and custom effects. Covers meta tags, RichTextEffect shaders, and dynamic content. Use when implementing dialogue systems OR formatted text. Keywords RichTextLabel, BBCode, [b], [color], [url], meta_clicked, RichTextEffect, dialogue.

Rich Text & BBCode

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

Available Scripts

rich_text_rainbow_effect.gd

Expert custom RichTextEffect that rotates colors over time.

rich_text_glitch_effect.gd

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

rich_text_typewriter_controller.gd

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

rich_text_meta_dispatch.gd

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

rich_text_image_scaler.gd

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

rich_text_hover_reactive.gd

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

rich_text_bbcode_sanitizer.gd

Security utility to prevent BBCode injection in public chat interfaces.

rich_text_gradient_generator.gd

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

rich_text_auto_scroller.gd

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

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 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

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
• [img] sizing — use width_unit / height_unit + RichTextLabel.ImageUnit (see migration-notes.md); scale with rich_text_image_scaler.gd
• Custom effects — register via custom_effects / install_effect(); examples: rich_text_rainbow_effect.gd, rich_text_glitch_effect.gd

User-Generated Rich Text

MANDATORY: 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. 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 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

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.