godot-ui-rich-text

富文本与 BBCode

BBCode 标签、可点击的 meta 链接和 RichTextEffect 着色器定义了格式化文本系统。

可用脚本

rich_text_rainbow_effect.gd

高级自定义 RichTextEffect，可随时间轮换颜色。

rich_text_glitch_effect.gd

具有空间抖动和透明度闪烁效果的专业恐怖风格故障特效。

rich_text_typewriter_controller.gd

对话管理器，可在动画过程中解析顺序事件标签（[pause]、[speed]）。

rich_text_meta_dispatch.gd

高级处理 meta 点击中的多前缀 URL（物品、任务、NPC）。

rich_text_image_scaler.gd

实用工具，可动态缩放 [img] 标签，使其匹配运行时字体大小。

rich_text_hover_reactive.gd

用于让文本片段响应鼠标悬停的信号和逻辑（音效/光标）。

rich_text_bbcode_sanitizer.gd

安全工具，用于防止公开聊天界面遭受 BBCode 注入。

rich_text_gradient_generator.gd

生成多段线性渐变，并使用细粒度的字符级标签。

rich_text_auto_scroller.gd

用于片尾字幕、新闻源和日志的平滑垂直自动滚动逻辑。

rich_text_syntax_highlighter.gd

用于 UI 代码块的简单正则表达式语法高亮模式。

切勿这样做（专业 UI 规则）

格式与渲染

• 切勿在紧密循环中使用复杂 BBCode——每帧解析含有 500 个标签的 10,000 字符字符串会严重拖慢性能。请缓存格式化后的字符串。
• 切勿忘记注册自定义特效——仅编写脚本还不够。你必须通过 Inspector 或 install_effect() 将实例添加到 RichTextLabel.custom_effects 列表中。
• 切勿在 [img] 中使用绝对像素大小——[img width=128] 在更高分辨率下会失效。使用 rich_text_image_scaler.gd 与行高同步。

点击与悬停体验

• 切勿使用没有视觉反馈的 [url]——如果文本在悬停时不会变色，或光标不会改变，玩家就不会知道它可以点击。请使用 rich_text_hover_reactive.gd。
• 切勿将布局逻辑硬编码到字符串中；应严格使用 BBCode 表格和对齐标签，确保文本结构保持灵活。
• 切勿通过逐帧修改 text 或 bbcode 字符串来制作打字机文本动画；应严格使用 visible_ratio 或 visible_characters，以避免高昂的解析开销和闪烁。
• 切勿在大型标题或动态 UI 中使用标准位图字体；应严格使用 **MSDF（多通道有符号距离场）**字体，确保在任何分辨率下轮廓和缩放都清晰锐利。
• 切勿在 meta_clicked 中执行繁重逻辑——此信号在主线程上触发。请使用它发出命令，并在需要时异步处理。

对话与叙事

• 切勿使用 visible_ratio 暂停打字机效果——visible_ratio 不适用于逐字符逻辑。请使用 visible_characters 和显式字符索引（rich_text_typewriter_controller.gd）。
• 切勿允许聊天标签中出现未经筛选的用户输入——用户可能输入 [img]huge_image_path[/img] 或 [color=transparent] 来破坏 UI。必须在将每个用户生成的字符串赋值给 text 前，先通过 rich_text_bbcode_sanitizer.gd 处理。

---

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

显示 API 决策

需求	API	必须
简单淡入 / 整行显示	visible_ratio + Tween	可内联（参见下方模式）
暂停 / 速度 / 事件标签（[pause]、[speed]）	visible_characters + 索引器	rich_text_typewriter_controller.gd

需要使用逐字符暂停 / 速度标签时，绝不要使用 visible_ratio。

不那么显而易见的标签与效果

跳过 [b] / [i] / [u] / [color] 的目录介绍——参见文档。遇到不那么显而易见的情况时，优先使用以下内容：

• [url=payload]…[/url] + meta_clicked — 优先使用 rich_text_meta_dispatch.gd
• [img] 尺寸设置 — 使用 width_unit / height_unit + RichTextLabel.ImageUnit（参见 migration-notes.md）；使用 rich_text_image_scaler.gd 缩放
• 自定义效果 — 通过 custom_effects / install_effect() 注册；示例：rich_text_rainbow_effect.gd、rich_text_glitch_effect.gd

用户生成的富文本

必须：在执行 RichTextLabel.text = … 前，对任何聊天、大厅或玩家输入路径使用 rich_text_bbcode_sanitizer.gd。

处理链接点击

优先使用 rich_text_meta_dispatch.gd。最简钩子：

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

专家级文本模式

1. 富文本 MSDF 描边（SDF）

在字体资源上启用 MSDF，并使用主题覆盖，以实现清晰的高分辨率描边和缩放。

# 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. 动画文本显示

简单淡入 — 对 visible_ratio 使用 Tween（保留 BBCode 效果；不重写字符串）：

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)

暂停 / 速度标签 — 必须使用 rich_text_typewriter_controller.gd，通过 visible_characters（而非 visible_ratio）控制显示。

3. 自定义 BBCode 效果（RichTextEffect）

通过扩展 RichTextEffect 定义自定义视觉标签（如 [relic]），以实现独特的游戏主题文本动画。

# 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

深入配方（按需）

LLM 无知规则：如果通用 Agent 在阅读之前不会知道某项内容，就将其放在此处或 scripts/ 中——绝不要删除，只能移动。

主题	参考
标签目录 + 4.7 img 单位	bbcode-tag-catalog.md

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在路由到同级领域时加载相关技能——不要预加载整个网络。

官方文档

• RichTextLabel 中的 BBCode — 标签语法、内置效果、图像，以及用于对话和格式化 UI 文案的 [url] 元数据。
• RichTextLabel — bbcode_enabled、visible_characters / visible_ratio、meta_clicked 和 custom_effects / install_effect()。
• RichTextEffect — 自定义 BBCode 效果的子类约定（bbcode ID + _process_custom_fx）。
• CharFXTransform — 彩虹／故障／自定义效果使用的逐字形颜色、偏移和 env 参数。
• 使用字体 — 使用 MSDF／动态字体，让标题和 BBCode 在不同分辨率下都能清晰缩放。
• GUI 皮肤设置 — 通过主题颜色／常量覆盖（轮廓、字体）设置样式，而无需将样式硬编码到 BBCode 字符串中。
• 尺寸和锚点 — 构建自适应对话框和日志面板，让富文本布局在分辨率变化时仍能正常显示。
• GUI 容器 — 将按钮／图标放在容器中；仅使用 RichTextLabel 显示正文。
• 自定义鼠标光标 — 悬停在 [url]／元数据区域时提供指针反馈。
• 游戏国际化 — 使用 tr() / CSV 键，让 BBCode 模板随时可用于本地化。
• 信号 — 连接 meta_clicked / 悬停信号，避免将游戏逻辑塞进标签中。
• Tween — 对 visible_ratio / visible_characters 使用补间动画，实现打字机式显示，而无需每帧重新解析 BBCode。

相关技能

前置要求

• godot-project-foundations — 在连接 RichTextLabel 对话界面前，了解场景树、Control 基础知识和资源导入。
• godot-ui-containers — 使用自适应 VBox/HBox/Scroll 布局容器，让富文本只负责显示正文，而不充当布局引擎。
• godot-signal-architecture — 使用类型化的元数据／悬停命令信号，让点击处理程序在主线程中保持精简。
• godot-gdscript-mastery — 掌握清理器、高亮器和效果脚本使用的 RegEx、@tool 和 RefCounted 辅助工具。

补充内容

• godot-ui-theming — 主题类型变体以及字体／描边覆盖设置，BBCode 应引用这些设置，而不是硬编码。
• godot-tweening — 用于打字机效果 visible_ratio 和自动滚动润色的生命周期安全 Tween。
• godot-input-handling — 跳过／继续和光标变化，可与 meta 悬停配合使用，且不会争抢 Control 焦点。
• godot-dialogue-system — 为 RichTextLabel 打字机控制器提供内容的行运行器和事件标签。
• godot-shaders-basics — 当 CharFX 不足以满足需求，且需要在文本面板周围使用画布项着色器时使用。

下游／使用方

• godot-genre-visual-novel — 依赖 BBCode、visible_characters 和 meta 选项链接的视觉小说对话框。
• godot-genre-educational — 复用净化器和高亮器的课程／文案 UI 及交互式富文本。
• godot-genre-romance — 复用打字机和 meta 分发模式的好感度对话呈现。

主索引

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。