Texturge ProDocs

从 Texturge Alpha 迁移

Texturge Beta 引入了全新的动画编译管线、数据结构与运行时架构。本文档帮助 Alpha 用户平滑升级。

架构变更概览

领域AlphaBeta
曲线资产UTextAnimation（旧序列资产）UGlyphAnimation（UMovieSceneSequence）
动画蓝图轨道数组 + 预定义参数UTextAnimationBlueprint + 蓝图变量即参数
轨道系统FTextAnimationTrack（10 条）+ FKeyFrame / EKeyInterpSequencer 原生 FloatChannel（UMovieSceneGlyphAnimationTrack / Section）
帧数据FAnimationFrameData（逐帧数组）FGlyphAnimationState（逐字形求值）
烘焙管线运行时内联编译（CompileFromAsset / EvaluateTime）FAnimationCompiler::BakeAllStages（编译期烘焙）
调度轨道内 CharacterDelay / SelectionMode 等 8 参数FGlyphScheduleInfo + Layer/Factory 调度 API
图层系统无（单轨道叠加）UGlyphAnimationLayer + UGlyphAnimationFactory（四混合模式）
阶段系统无Intro / Default / Outro 阶段系统
运行时UTextAnimator 驱动（含编译与求值）分离：UTextAnimationStageController（求值）+ 编译器（烘焙）
指纹缓存无CityHash64 双指纹（文本 + 蓝图）
富文本标签映射（UTextAnimationDataAsset）<anim id="..."> 标签 + FAnimationEntry 覆盖映射
本地化语义锚点（缓存/扫描机制）ULocalizationSubsystem（锚点重定位接口，死机制已删除）

关键类映射

蓝图与资产

AlphaBeta
UTextAnimation（旧序列）UGlyphAnimation（UMovieSceneSequence）
动画蓝图资产UTextAnimationBlueprint（UBlueprint）
UTextAnimationBlueprintGeneratedClass（旧编译输出）同名新生成类（CompiledTracks 兼容保留）
蓝图实例UTextAnimInstance（CDO + 烘焙缓存）

编译与烘焙

AlphaBeta
CompileFromAsset() / EvaluateTime()FAnimationCompiler::BakeAllStages(BP, Text, Customizer)
FTextAnimationTrack / FKeyFrameFGlyphCurveSet + Sequencer FloatChannel
FAnimationFrameDataFGlyphAnimationState（10 字段）
FPerCharacterTrackDataFGlyphScheduleInfo（StartDelay / bSkipAnimation）
DataBridge（旧数据桥）已删除（ReadLegacyTracks 不再存在）
无指纹ComputeTextFingerprint / ComputeBlueprintFingerprint（CityHash64）

运行时

AlphaBeta
UTextAnimator 播放控制UTextAnimationStageController（纯文本路径）
UTextAnimator 富文本管线UTextAnimator（仅富文本编排，编译职责移交）
UAnimatedTextBlock同（内部改为 StageController 驱动）
轨道式混合UGlyphAnimationLayer / UGlyphAnimationFactory + ETextAnimationBlendMode

迁移步骤

  1. 备份项目 — 迁移前创建完整备份（迁移为单向操作）

  2. 更新插件 — 移除 Alpha 插件，放入 Beta（Plugins/Texturge），确认 .uplugin VersionName 为 1.0.0-beta.1

  3. 重新生成项目文件 — 右键 .uproject → 生成 Visual Studio 项目文件，重新编译；确认 Build.cs 依赖 Texturge 模块

  4. 重建动画资产：

    • 创建 UTextAnimationBlueprint（内容浏览器右键 → Texturge → 文本动画蓝图）
    • 动画面板添加字形动画（UGlyphAnimation）资产，在 Sequencer 中重建关键帧曲线
    • 旧轨道参数（SelectionMode / CharacterDelay / TimingMode 等）已删除——延迟改用 FGlyphScheduleInfo::StartDelay，选择模式改用 SkipAt / 分类 API

  5. 迁移 BuildDefaultAnimation — 覆盖 BuildDefaultAnimation(int32 GlyphCount, const FString& Text)（返回 FBakedStage）：

// Alpha（示意）
FBakedAnimation OldBuild(int32 GlyphCount, const FString& Text);

// Beta
FBakedStage BuildDefaultAnimation_Implementation(int32 GlyphCount, const FString& Text)
{
    TArray<FGlyphScheduleInfo> Schedule = BuildScheduleInfos(Text);
    UGlyphAnimationLayer* BaseLayer = CreateLayer(GlyphAnimations[0], ETextAnimationBlendMode::Override, Schedule);
    UGlyphAnimationFactory* Factory = CreateFactory(BaseLayer, Schedule);
    for (int32 i = 1; i < GlyphAnimations.Num(); ++i)
    {
        Factory->AddLayer(CreateLayer(GlyphAnimations[i], ETextAnimationBlendMode::Additive, Schedule));
    }
    return Factory->Bake();
}
  1. 更新 C++ 播放代码：
// Alpha（示意）
Animator->StartAnimating();

// Beta（手动路径）
FBakedAnimation Baked = FAnimationCompiler::BakeAllStages(AnimationBlueprint, Text);
UTextAnimationStageController* Controller = NewObject<UTextAnimationStageController>(this);
Controller->Initialize(&Baked, AnimationBlueprint);
Controller->Play();

TIP

UMG 控件路径无需手动管理——设置 UAnimatedTextBlock::TextAnimationBlueprint 后控件自动完成编译、初始化与播放，直接调用 Play() 即可。

  1. 迁移富文本标签 — 将 UTextAnimationDataAsset 的 Entries 重建：TagName 对应新标签语法 <anim id="TagName">…</>，动画蓝图引用改用 Type 字段（TObjectPtr<UTextAnimationBlueprint>）

  2. 参数系统迁移 — 旧 C++ 预定义参数（DefaultGlyphDelay / AnimationIntensity 等）已删除：在蓝图类默认值（Class Defaults）中自行声明变量，运行时通过 SetBlueprintVariable 系列节点 / UAnimParameterOverrides 覆写

  3. 重新编译所有动画蓝图 — 打开每个 UTextAnimationBlueprint 执行编译（Compile），确认无编译错误

  4. 测试所有动画 — 在设计器视口（STextAnimationDesignerView）的预览模式中逐一验证；运行自动化测试（Texturge.Animation.* 组）确认回归

不再存在的概念

以下 Alpha 概念在 Beta 中已删除或替代：

  • FTextAnimationTrack 8 个专用参数（SelectionMode / SelectionInterval / RandomProbability / CharacterSpacing / DurationControl / FixedTotalDuration / bInvertOpacity 等）→ 由 FGlyphScheduleInfo + Layer/Factory API 替代（结构保留 @deprecated 兼容）
  • FKeyFrame / EKeyInterp 自定义插值 → Sequencer 原生 FloatChannel 插值
  • FAnimationFrameData 逐帧数组 → FGlyphAnimationState 逐字形求值
  • DataBridge::ReadLegacyTracks / ReadLegacyKeyframes → 已删除
  • MergeSingleCurve / MergeLayerCurves 曲线合并 → 已彻底移除（插值误差问题），改为逐层独立求值
  • FAnimationLayerSetup 中间包装类型 → 已排除的架构模式，不要引入
  • NeedsRebake() 运行时检查 → 缓存失效由控件层 / 预览层负责
  • SDF 字体图集 / 纹理烘焙 → 仅逐字形曲线动画

常见问题

Q: 迁移后动画效果不同？ A: Beta 数据流完全重写，微调参数映射方式不同。在蓝图 BuildDefaultAnimation 中用 Layer / Factory 的 51 个微调函数逐步调整；SetStartDelayAt(-1, X) + SetDelayAt(-1, Y) 恢复错峰节奏。

Q: 旧资产可以降级回 Alpha 吗？ A: 不可以。迁移是单向操作，请确保迁移前已备份。

Q: 我的项目有自定义 C++ 代码怎么办？ A: 检查所有 #include 引用，将 Alpha 类名替换为 Beta 对应类名（见映射表）。编译后修复剩余 API 差异；FTextAnimationTrack 等旧结构仅作序列化兼容保留，不要在新代码中使用。

images/migration-overview.png — 迁移流程概览图：左侧 Alpha 旧资产（UTextAnimation + FTextAnimationTrack 轨道数组 + FAnimationFrameData），右侧 Beta 新架构（UTextAnimationBlueprint + UGlyphAnimation + Layer/Factory 烘焙），中间标注 10 个迁移步骤与类映射关系 — Migration overview diagram: Alpha legacy assets on the left (UTextAnimation + FTextAnimationTrack track arrays + FAnimationFrameData), Beta architecture on the right (UTextAnimationBlueprint + UGlyphAnimation + Layer/Factory baking), the 10 migration steps and class mappings annotated in the middle