Migrating from Texturge Alpha

Texturge Beta introduces a brand-new animation compilation pipeline, data structures, and runtime architecture. This document helps Alpha users upgrade smoothly.

Architecture Change Overview

Area	Alpha	Beta
Curve assets	UTextAnimation (legacy sequence asset)	UGlyphAnimation (UMovieSceneSequence)
Animation Blueprint	track array + predefined parameters	UTextAnimationBlueprint + Blueprint variables as parameters
Track system	FTextAnimationTrack (10) + FKeyFrame / EKeyInterp	native Sequencer FloatChannel (UMovieSceneGlyphAnimationTrack / Section)
Frame data	FAnimationFrameData (per-frame arrays)	FGlyphAnimationState (per-glyph evaluation)
Bake pipeline	runtime inline compilation (CompileFromAsset / EvaluateTime)	FAnimationCompiler::BakeAllStages (compile-time baking)
Scheduling	8 in-track parameters (CharacterDelay / SelectionMode etc.)	FGlyphScheduleInfo + Layer/Factory scheduling API
Layer system	none (single-track stacking)	UGlyphAnimationLayer + UGlyphAnimationFactory (four blend modes)
Stage system	none	Intro / Default / Outro stage system
Runtime	UTextAnimator drives everything (compile + evaluation)	separated: UTextAnimationStageController (evaluation) + compiler (baking)
Fingerprint caching	none	CityHash64 dual fingerprints (text + Blueprint)
Rich text	tag mapping (UTextAnimationDataAsset)	<anim id="..."> tags + FAnimationEntry override maps
Localization	semantic anchors (cache/scan mechanism)	ULocalizationSubsystem (anchor relocation interface, dead mechanism removed)

Key Class Mappings

Blueprints & Assets

Alpha	Beta
UTextAnimation (legacy sequence)	UGlyphAnimation (UMovieSceneSequence)
animation Blueprint asset	UTextAnimationBlueprint (UBlueprint)
UTextAnimationBlueprintGeneratedClass (legacy compile output)	same-named new generated class (CompiledTracks kept for compatibility)
Blueprint instance	UTextAnimInstance (CDO + bake cache)

Compilation & Baking

Alpha	Beta
CompileFromAsset() / EvaluateTime()	FAnimationCompiler::BakeAllStages(BP, Text, Customizer)
FTextAnimationTrack / FKeyFrame	FGlyphCurveSet + Sequencer FloatChannel
FAnimationFrameData	FGlyphAnimationState (10 fields)
FPerCharacterTrackData	FGlyphScheduleInfo (StartDelay / bSkipAnimation)
DataBridge (legacy data bridge)	removed (ReadLegacyTracks no longer exists)
no fingerprints	ComputeTextFingerprint / ComputeBlueprintFingerprint (CityHash64)

Runtime

Alpha	Beta
UTextAnimator playback control	UTextAnimationStageController (plain text path)
UTextAnimator rich text pipeline	UTextAnimator (rich text orchestration only; compilation moved out)
UAnimatedTextBlock	same (internally driven by StageController)
track-based blending	UGlyphAnimationLayer / UGlyphAnimationFactory + ETextAnimationBlendMode

Migration Steps

1. Back up your project — create a full backup before migrating (migration is one-way)

2. Update the plugin — remove the Alpha plugin and install Beta (Plugins/Texturge); confirm the .uplugin VersionName is 1.0.0-beta.1

3. Regenerate project files — right-click the .uproject → Generate Visual Studio project files, recompile; confirm the Build.cs depends on the Texturge module

4. Rebuild animation assets:

   • Create a UTextAnimationBlueprint (right-click in the Content Browser → Texturge → Text Animation Blueprint)
   • Add glyph animation (UGlyphAnimation) assets in the animation panel and rebuild keyframe curves in Sequencer
   • Legacy track parameters (SelectionMode / CharacterDelay / TimingMode etc.) are removed — use FGlyphScheduleInfo::StartDelay for delays and SkipAt / classification APIs for selection modes

5. Migrate BuildDefaultAnimation — override BuildDefaultAnimation(int32 GlyphCount, const FString& Text) (returns FBakedStage):

// Alpha (illustrative)
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();
}

6. Update C++ playback code:

// Alpha (illustrative)
Animator->StartAnimating();

// Beta (manual path)
FBakedAnimation Baked = FAnimationCompiler::BakeAllStages(AnimationBlueprint, Text);
UTextAnimationStageController* Controller = NewObject<UTextAnimationStageController>(this);
Controller->Initialize(&Baked, AnimationBlueprint);
Controller->Play();

TIP

The UMG widget path needs no manual management — set UAnimatedTextBlock::TextAnimationBlueprint and the widget handles compilation, initialization, and playback automatically; just call Play().

7. Migrate rich text tags — rebuild UTextAnimationDataAsset Entries: TagName corresponds to the new tag syntax <anim id="TagName">…</>; animation Blueprint references use the Type field (TObjectPtr<UTextAnimationBlueprint>)

8. Migrate the parameter system — legacy C++ predefined parameters (DefaultGlyphDelay / AnimationIntensity etc.) are removed: declare your own variables in the Blueprint Class Defaults and override them at runtime via the SetBlueprintVariable family of nodes / UAnimParameterOverrides

9. Recompile all animation Blueprints — open every UTextAnimationBlueprint and run Compile, confirming no compile errors

10. Test all animations — verify each in the preview modes of the designer viewport (STextAnimationDesignerView); run the automated tests (Texturge.Animation.* group) to confirm no regressions

Concepts That No Longer Exist

The following Alpha concepts are removed or replaced in Beta:

• FTextAnimationTrack 8 dedicated parameters (SelectionMode / SelectionInterval / RandomProbability / CharacterSpacing / DurationControl / FixedTotalDuration / bInvertOpacity etc.) → replaced by FGlyphScheduleInfo + Layer/Factory APIs (struct kept @deprecated for compatibility)
• FKeyFrame / EKeyInterp custom interpolation → native Sequencer FloatChannel interpolation
• FAnimationFrameData per-frame arrays → FGlyphAnimationState per-glyph evaluation
• DataBridge::ReadLegacyTracks / ReadLegacyKeyframes → removed
• MergeSingleCurve / MergeLayerCurves curve merging → fully removed (interpolation error issues), replaced by per-layer independent evaluation
• FAnimationLayerSetup intermediate wrapper type → an excluded architectural pattern; do not introduce it
• NeedsRebake() runtime check → cache invalidation handled by the widget / preview layers
• SDF font atlas / texture baking → per-glyph curve animation only

FAQ

Q: The animation looks different after migration? A: Beta’s data flow was completely rewritten and the parameter mapping differs. Adjust gradually with the 51 tweak functions of Layer / Factory in the Blueprint BuildDefaultAnimation; SetStartDelayAt(-1, X) + SetDelayAt(-1, Y) restores the stagger rhythm.

Q: Can legacy assets be downgraded back to Alpha? A: No. Migration is one-way — make sure to back up before migrating.

Q: What about my custom C++ code? A: Check all #include references and replace Alpha class names with their Beta counterparts (see the mapping tables). Fix remaining API differences after compiling; legacy structures like FTextAnimationTrack are kept only for serialization compatibility — do not use them in new code.