Texturge Pro文档

基础标签

Texturge 的富文本动画系统通过 UTextAnimationDataAsset 将动画标签（<anim id="...">）映射到 UTextAnimationBlueprint。

设计流程：创建标签映射 → 配置数据资产 → 在 UAnimatedRichTextBlock 中通过标签触发动画。

组件概述

适用场景：了解富文本动画系统各组件之间的协作关系。

UAnimatedRichTextBlock

UAnimatedRichTextBlock 是 URichTextBlock 的子类，支持通过富文本标签触发逐字动画。内部由私有 FRichTextMarshaller 完成解析与渲染树构建，UTextAnimator 驱动多条目动画播放。样式集、装饰器、数据表等能力继承自引擎 URichTextBlock。

UTextAnimationDataAsset

UTextAnimationDataAsset 是 UDataAsset，维护标签映射表。Entries 是 TArray<FAnimationEntry>，每个条目包含：

  • TagName — 标签标识，如 "wave"、"shake"，对应文本中的 <anim id="wave">
  • Type — 指向文本动画蓝图（UTextAnimationBlueprint）的资产引用
  • 6 个参数覆盖映射 — Float、Int、Bool、Vector、Color、Vector2D 的条目级默认参数覆盖
  • bHideFirstFrame — 顺序播放时未执行条目提前透明
images/dataasset-editor.png — UTextAnimationDataAsset 数据资产编辑器截图：Entries 数组展开，每个条目显示标签名（wave/shake/bounce）、动画蓝图资产选择器（TAB_Wave/TAB_Shake/TAB_Bounce）与 6 组参数覆盖映射 — UTextAnimationDataAsset editor screenshot: Entries array expanded, each entry showing TagName (wave/shake/bounce), blueprint asset selector (TAB_Wave/TAB_Shake/TAB_Bounce) and six parameter override maps

创建数据资产

适用场景：首次创建标签到动画蓝图的映射资产。

  1. 内容浏览器右键 → 数据 > 数据资产
  2. 类选择对话框中搜索选择文本动画数据资产（UTextAnimationDataAsset）
  3. 命名为 DA_DialogAnimations
  4. 双击打开数据资产编辑器

TIP

建议按用途命名数据资产，例如 DA_DialogAnimations（对话用）、DA_UIAnimations（界面用），便于团队协作时快速定位。

配置标签映射

适用场景：在数据资产中添加标签到动画蓝图的映射条目。

  1. 展开 Entries 数组，点击 + 添加元素
  2. 设置 TagName 为 "wave"
  3. 设置 Type 指向之前创建的 TAB_Wave 动画蓝图
  4. （可选）配置参数覆盖映射，为条目提供默认蓝图变量值
  5. 重复添加更多标签："shake" → TAB_Shake、"bounce" → TAB_Bounce
images/tag-to-animation-mapping.png — 映射关系示意图：左侧文本中的 标签，中间数据资产 Entries 表（TagName → Type → 参数覆盖），右侧动画蓝图 TAB_Wave — Mapping diagram: tag in the text on the left, DataAsset Entries table in the middle (TagName → Type → parameter overrides), TAB_Wave blueprint on the right

使用 UAnimatedRichTextBlock

适用场景：在 UMG 控件中配置富文本动画控件并编写动画标签文本。

在 UMG 中设置

  1. 创建或打开一个 UMG Widget 蓝图
  2. 在面板中搜索 动画多格式文本块 拖入画布
  3. 配置多格式文本块的基础配置（如默认样式、样式集、装饰器等，参照官方文档）
  4. 在细节面板设置 动画数据资产 为 DA_DialogAnimations
  5. 在 文本 属性中写入包含标签的富文本

富文本格式

使用标准 XML 标签语法——标签名为 anim，动画标识通过 id 属性指定：

<anim id="wave">Hello World!</>

当数据资产包含 TagName = "wave" 的条目时，文本 “Hello World!” 使用 TAB_Wave 动画蓝图渲染。

标签解析流程

  1. FTagParser 解析文本为 FTagNode 树（剥离标签，输出纯文本）
  2. FRenderTreeBuilder 结合数据资产构建渲染树（<anim> 匹配 → AnimationLayer 节点）
  3. 每个 AnimationLayer 节点实例化对应条目的动画实例（UTextAnimator 驱动）
  4. 样式标签（StyleLayer）委托 UE5 富文本样式系统处理

组合多个标签

适用场景：在同一段文本中使用不同动画标签实现分段差异化效果。

<anim id="wave">欢迎来到</> <anim id="shake">地下城！</>
  1. 不同标签段落使用各自的动画蓝图独立播放
  2. 过渡处字符按各自时间线推进，互不干扰
  3. 未包裹在标签内的纯文本静态显示（可通过 bSequentialPlayback 控制多条目顺序/同时播放）

NOTE

未匹配到任何条目的 <anim> 标签会输出警告日志并作为 StyleLayer 处理（保留标签，无动画）。未包裹的纯文本不触发动画。

images/multi-tag-result.png — 多标签渲染效果截图：同一文本中 "欢迎来到" 波浪动画、"地下城！" 抖动动画，两者同时播放且互不干扰 — Multi-tag rendering result screenshot: "欢迎来到" with wave animation and "地下城！" with shake animation in the same text, playing simultaneously without interference

注意事项

适用场景：排查标签解析失败、动画不播放等常见配置错误。

  1. 标签匹配忽略大小写——<anim id="Wave"> 与 TagName = "wave" 可匹配（ClassifyNode 使用 ESearchCase::IgnoreCase）
  2. 标签必须正确闭合——<anim id="wave">text 缺少 </> 时自动闭合并输出警告
  3. id 属性必须存在——<anim> 无 id 时分类为 StyleLayer（无动画）
  4. 配置数据资产时 TagName 不含尖括号，仅为标识符（如 "wave"）
  5. 标签名最长 32 字符，仅允许 [A-Za-z0-9_-]