运行时核心类

运行时模块（Source/Texturge/Public）提供以下核心类。按继承关系分为 UObject 体系、UMG 控件体系与纯 C++ 工具三类。

类层级

UObject
├── UTextAnimationBlueprint          (UBlueprint)      — 动画蓝图资产
├── UTextAnimationBlueprintGeneratedClass (UBlueprintGeneratedClass) — 编译输出生成类
├── UTextAnimInstance                — 蓝图实例（烘焙缓存 + BuildDefaultAnimation 事件）
├── UTextAnimationStageController    — 阶段控制器（运行时播放引擎）
├── UTextAnimator                    — 打字机管线引擎（富文本路径）
├── UGlyphAnimation                  (UMovieSceneSequence) — 字形动画曲线资产
├── UGlyphAnimationLayer             — 图层包装（曲线副本 + 调度 + 微调）
├── UGlyphAnimationFactory           — 多图层合并烘焙器
├── UTextAnimationDataAsset          (UDataAsset)      — 富文本标签 → 动画映射
├── UAnimParameterOverrides          — 实例级参数覆盖容器
├── UDialogWidget                    (UUserWidget)     — 对话控件
├── UEventSoundComponent             (UActorComponent) — 事件音效组件
└── ULocalizationSubsystem           (UGameInstanceSubsystem) — 本地化子系统

UMG 控件体系
├── UAnimatedTextBlock               (UTextBlock)      — 纯文本动画控件
└── UAnimatedRichTextBlock           (URichTextBlock)  — 富文本动画控件

纯 C++ 工具
├── FAnimationCompiler               — 静态编译函数集
├── FGlyphScheduleBuilder            — 调度构建工具
└── FTagParser / FRenderTreeBuilder  — 富文本解析与渲染树构建

UAnimatedTextBlock

继承 UTextBlock 的 UMG 控件，内部持有 UTextAnimationStageController 并自动管理其生命周期。支持逐字打字机动画、循环播放与运行时蓝图变量覆写。

UCLASS(BlueprintType, Blueprintable, meta = (DisplayName = "动画文本块"))
class TEXTURGE_API UAnimatedTextBlock : public UTextBlock

配置属性

属性	类型	默认值	说明
`TextAnimationBlueprint`	`TObjectPtr<UTextAnimationBlueprint>`	—	驱动动画的蓝图资产
`ParameterOverrides`	`TObjectPtr<UAnimParameterOverrides>`	—	实例级参数覆盖（Instanced）
`bAutoPlay`	`bool`	`false`	初始化后自动播放
`bLoopPlayback`	`bool`	`false`	循环播放

播放控制（BlueprintCallable）

函数	DisplayName	说明
`Play()`	播放	开始逐字揭示动画
`Pause()`	暂停	暂停播放
`Resume()`	恢复	恢复暂停的播放
`Stop()`	停止	停止并重置动画
`SkipToEnd()`	跳转到结尾	跳过动画直接显示全部文本
`IsAnimating()`	是否正在播放	BlueprintPure，是否正在播放

蓝图变量设置（6 重载）

函数	类型	DisplayName
`SetBlueprintVariable(FName, float)`	float	设置蓝图变量
`SetBlueprintVariable_Int(FName, int32)`	int32	设置蓝图变量 (Int)
`SetBlueprintVariable_Bool(FName, bool)`	bool	设置蓝图变量 (Bool)
`SetBlueprintVectorVariable(FName, FVector)`	FVector	设置蓝图变量 (Vector)
`SetBlueprintColorVariable(FName, FLinearColor)`	FLinearColor	设置蓝图变量 (Color)
`SetBlueprintVector2DVariable(FName, FVector2D)`	FVector2D	设置蓝图变量 (Vector2D)

蓝图委托（BlueprintAssignable）

委托	签名	说明
`OnCharacterRevealedBP`	`FOnAnimTextCharRevealedBP(int32 RevealedCount)`	字形揭示时触发（回调已揭示计数）
`OnAnimationCompleteBP`	`FOnAnimTextAnimationCompleteBP`	动画完成时触发

NOTE

文本内容通过 UTextBlock 基类的 Text 属性设置，控件内部缓存为 FullText 并在 SynchronizeProperties() 中触发编译与播放。

UAnimatedRichTextBlock

继承 URichTextBlock，使用 UTextAnimator 驱动富文本逐字动画。通过 UTextAnimationDataAsset 将标签映射到动画蓝图，支持多条目顺序/同时播放。

UCLASS(meta = (DisplayName = "动画多格式文本块"))
class TEXTURGE_API UAnimatedRichTextBlock : public URichTextBlock

配置属性

属性	类型	默认值	说明
`AnimationData`	`TObjectPtr<UTextAnimationDataAsset>`	—	标签 → 动画蓝图映射数据资产
`bAutoPlay`	`bool`	`false`	初始化后自动播放
`bLoopPlayback`	`bool`	`false`	循环播放
`bSequentialPlayback`	`bool`	`false`	顺序播放（开启后各条目动画依次播放，关闭则同时播放）

播放控制（BlueprintCallable）

Play() / Pause() / Resume() / Stop() / SkipToEnd() / IsAnimating() — 与 UAnimatedTextBlock 同构。

蓝图委托（BlueprintAssignable）

委托	签名	说明
`OnCharacterRevealedBP`	`FOnCharacterRevealedBP(int32 CharIndex, FString Character)`	字形揭示时触发（码点索引 + 字符）
`OnAnimationCompleteBP`	`FOnAnimatedRichTextAnimationCompleteBP`	动画完成时触发

NOTE

样式集、装饰器、数据表、文本整形与自动换行继承自 URichTextBlock 基类，插件不重复实现。内部由私有 FRichTextMarshaller / SAnimatedRichTextBlock 完成逐字形渲染。

UTextAnimationStageController

运行时动画的中央调度单元——数据驱动控制器（非控件），管理 FBakedAnimation 的播放、暂停、阶段转换与求值。

UCLASS(BlueprintType, meta = (DisplayName = "文本动画阶段控制器"))
class TEXTURGE_API UTextAnimationStageController : public UObject

C++ 注入接口

方法	说明
`Initialize(const FBakedAnimation* InAnimation, UTextAnimationBlueprint* InBlueprint)`	注入烘焙数据与源蓝图引用
`PublishBakedAnimation(const FBakedAnimation& NewAnimation)`	发布新烘焙动画（GameThread 安全）
`EvaluateGlyph(int32 GlyphIndex)`	单字形求值，返回 `FGlyphAnimationState`

播放控制（BlueprintCallable）

函数	DisplayName	说明
`Play()`	播放	开始播放
`Pause()`	暂停	暂停时间推进
`Resume()`	恢复	恢复播放
`Stop()`	停止	停止并重置
`RevealAll()`	揭示所有	立即揭示所有字形
`SetPlayDirection(EStagePlayDirection)`	设置播放方向	Forward / Reverse / PingPong
`SetLoop(bool)`	设置循环	启用循环播放
`TickAnimation(float DeltaTime)`	Tick 动画	每帧推进动画时钟
`EvaluateAllGlyphs(TArray<FGlyphAnimationState>& OutStates)`	评估所有字形	批量求值所有字形状态

查询（BlueprintPure）

函数	DisplayName	返回
`IsPlaying()`	是否正在播放	`bool`
`IsComplete()`	是否完成	`bool`
`GetCurrentStage()`	获取当前阶段	`EAnimationStage`
`GetStageTime()`	获取阶段时间	`float`
`GetRevealedGlyphCount()`	获取已揭示字数	`int32`
`GetTotalGlyphCount()`	获取总字数	`int32`

委托（C++ 多播）

委托	签名	触发时机
`OnGlyphRevealed`	`FOnGlyphRevealed(int32 GlyphIndex, TCHAR Character)`	字形首次揭示（反向播放时位清除可再次广播）
`OnStageChanged`	`FOnStageChanged(EAnimationStage From, EAnimationStage To)`	阶段切换
`OnAnimationComplete`	`FOnAnimationComplete`	动画完成

TIP

播放方向为 Reverse / PingPong 时，控制器按阶段时钟包裹求值；RevealedGlyphFlags 位图保证 OnGlyphRevealed 去重广播。

UTextAnimator

打字机管线引擎，专为 UAnimatedRichTextBlock 设计。全部为普通 C++ 方法，不暴露蓝图节点，由控件内部调用。

UCLASS(meta = (DisplayName = "文本动画器", ToolTip = "打字机动画管线引擎"))
class TEXTURGE_API UTextAnimator : public UObject

输入设置

方法	说明
`SetPlainText(const FString&)`	设置纯文本（非 RichText 路径）
`SetRichText(const FString&)`	设置富文本（渲染树驱动管线）
`SetAnimationData(UTextAnimationDataAsset*)`	设置条目映射资产（富文本路径）
`SetAnimationBlueprint(UTextAnimationBlueprint*)`	设置单一蓝图（纯文本路径）
`SetPlaybackMode(EPlaybackMode)`	Duration / CPS 模式
`SetCPS(float)`	每秒字形数（CPS ≥ 1.0）
`SetPlayMode(EPlayMode)`	Forward / Reverse / PingPong
`SetPlaySpeedMultiplier(float)`	播放倍速
`SetSequentialPlayback(bool)`	多条目顺序播放
`SetMaxLoopCount(int32)`	最大循环次数（≤0 无限）

播放控制

StartAnimating(bool bRevealAll = false) / TickAnimation(float) / Pause() / Resume() / Stop() / SkipToEnd()

数据查询

方法	说明
`IsAnimating()`	是否正在播放
`GetCurrentCharIndex()`	当前码点索引
`GetCharacterCount()`	总码点数
`GetGlyphIndexForCodeUnit(int32)`	码元 → 字形映射（代理对两码元映射同一字形）
`GetCurrentFrameData(int32)`	单字形当前帧状态（未揭示字形返回恒等帧）
`GetCurrentFrameDataArray()`	全部字形当前帧数组（渲染缓存）
`GetAccumulatedLetterSpacing(int32)`	累计字间距
`SetPreviewFrameDataOverride(const TArray<FGlyphAnimationState>&)`	编辑器预览帧数据注入

测试注入接口

SetAnimInstance(UTextAnimInstance*) / SetEntryAnimInstance(int32, UTextAnimInstance*) — 双注入接口，播放引擎免编译蓝图可测试。

UTextAnimationBlueprint

动画蓝图资产，继承 UBlueprint。设计师在编辑器中添加 UGlyphAnimation 曲线资产、配置阶段过渡并声明蓝图变量（蓝图变量即参数）。

UCLASS(BlueprintType, meta = (DisplayName = "文本动画蓝图"))
class TEXTURGE_API UTextAnimationBlueprint : public UBlueprint

属性

属性	类型	说明
`Tracks`	`TArray<FTextAnimationTrack>`	旧版轨道数组（@deprecated，兼容保留）
`GlyphAnimations`	`TArray<TObjectPtr<UGlyphAnimation>>`	字形动画资产列表（由动画面板管理）
`StageTransitionConfig`	`FStageTransitionConfig`	阶段过渡 CrossFade 配置（参与指纹哈希）
`VariableNameToGuidMap`	`TMap<FName, FGuid>`	变量名 → GUID 映射（稳定标识）
`CompileCount`	`uint32`	编译计数器（每次编译递增，参与指纹哈希）

函数

方法	说明
`GetTotalDuration()`	BlueprintPure，所有轨道总时长
`GetTrackById(const FGuid&)`	BlueprintPure，按 ID 查找轨道索引（未找到返回 -1）
`CreateAnimInstance()`	创建 `UTextAnimInstance` 实例
`OnVariableAdded/Renamed/Removed(FName)`	蓝图变量变更通知（编辑器内部使用）

UTextAnimInstance

蓝图生成的实例（CDO 是烘焙缓存持有者）。C++ 层不提供任何预定义变量——设计师在蓝图类默认值（Class Defaults）中自行声明变量，在 BuildDefaultAnimation 事件中读取。

UCLASS(BlueprintType, meta = (DisplayName = "文本动画实例"))
class TEXTURGE_API UTextAnimInstance : public UObject

蓝图变量设置（4 重载）

函数	类型	DisplayName
`SetBlueprintVariable(FName, float)`	float	设置蓝图变量
`SetBlueprintVectorVariable(FName, FVector)`	FVector	设置蓝图变量 (Vector)
`SetBlueprintColorVariable(FName, FLinearColor)`	FLinearColor	设置蓝图变量 (Color)
`SetBlueprintVector2DVariable(FName, FVector2D)`	FVector2D	设置蓝图变量 (Vector2D)

NOTE

UTextAnimInstance 仅提供 4 个重载（float / FVector / FLinearColor / FVector2D），int32 与 bool 蓝图变量由控件层 UAnimatedTextBlock 的对应重载写入。

调度与阶段构建

函数	说明
`BuildScheduleInfos(const FString& Text)`	静态 BlueprintCallable，遍历码点生成 `TArray<FGlyphScheduleInfo>`（预填索引、字符与字形分类）
`BuildDefaultAnimation(int32 GlyphCount, const FString& Text)`	BlueprintNativeEvent，覆盖此事件自定义默认阶段动画，返回 `FBakedStage`

查询与其他

函数	说明
`GetAnimationByName(FName)`	按名称从蓝图资产中查找 `UGlyphAnimation`
`GetCharacterCount()`	BlueprintPure，当前编译文本字符数
`EvaluateBaked(float InTime)`	用缓存烘焙数据求值，返回全部字形帧数据
`ResolveAnimationReferences()`	从蓝图资产同步蓝图变量值
`PostInitProperties()`	生命周期钩子

数据成员

成员	类型	说明
`SourceBlueprint`	`TObjectPtr<UTextAnimationBlueprint>`	源蓝图资产引用
`CharCount`	`int32`	编辑时的字形数
`CachedBakedAnimation`	`FBakedAnimation`	缓存的烘焙动画数据
`bHasBakedAnimation`	`bool`	烘焙数据是否就绪
`CachedBlueprintFingerprint`	`uint64`	蓝图指纹缓存

UGlyphAnimation

字形动画曲线资产，继承 UMovieSceneSequence。每个资产内部是一个 UMovieScene，通过 UMovieSceneGlyphAnimationTrack 存储 21 通道关键帧。

UCLASS(BlueprintType, MinimalAPI, meta = (DisplayName = "字形动画"))
class TEXTURGE_API UGlyphAnimation : public UMovieSceneSequence

蓝图函数

函数	说明
`GetDuration()`	BlueprintPure，动画总时长（秒）
`GetTrackTypes()`	返回 `TArray<ETextAnimationTrackType>`，动画包含的轨道类型列表
`HasTrackType(ETextAnimationTrackType)`	检查指定轨道类型是否存在

NOTE

曲线提取（FAnimationCompiler::ExtractCurves）基于 MovieScene 内所有 Track / Section 的 GetSignature() 做缓存，Sequencer 编辑后签名变化自动失效。

UAnimParameterOverrides

每个控件实例（Instanced per-widget）的参数覆盖容器，存储蓝图变量名 → 实例级覆盖值的映射。

UCLASS(meta = (DisplayName = "动画参数覆盖"))
class TEXTURGE_API UAnimParameterOverrides : public UObject
{
    TMap<FName, float>         FloatOverrides;
    TMap<FName, int32>         IntOverrides;
    TMap<FName, bool>          BoolOverrides;
    TMap<FName, FVector>       VectorOverrides;
    TMap<FName, FLinearColor>  ColorOverrides;
    TMap<FName, FVector2D>     Vector2DOverrides;
};

烘焙时由 ApplyAnimParamOverridesToInstance<Owner> 模板（AnimParamOverrideUtils.h）将覆盖写入烘焙临时实例。TAnimParamTraits<T, Owner> 为 C++ 类型到 TMap 成员的编译期映射，新增类型只需添加 TMap 字段 + 一行 DECLARE_ANIM_PARAM_TRAIT 特化。

images/runtime-classes.png — 运行时类关系图：UTextAnimationBlueprint → FAnimationCompiler → FBakedAnimation（含三个 FBakedStage 与 FBakedGlyph 多层 FPerLayerCurves），左侧 UAnimatedTextBlock 通过 UTextAnimationStageController 驱动求值，右侧 UAnimatedRichTextBlock 通过 UTextAnimator 驱动，底部 UAnimParameterOverrides 以 Instanced 方式挂在控件上 — Runtime class relationship diagram: UTextAnimationBlueprint → FAnimationCompiler → FBakedAnimation (with three FBakedStage and FBakedGlyph multi-layer FPerLayerCurves), UAnimatedTextBlock driven by UTextAnimationStageController on the left, UAnimatedRichTextBlock driven by UTextAnimator on the right, UAnimParameterOverrides Instanced on widgets at the bottom