ZenBlink Documentation / Upgrade from ZenBlink 2 to ZenBlink 3

Upgrading from ZenBlink 2 to ZenBlink 3

Manual rebuild required: ZenBlink 3 is not backward compatible with ZenBlink 2 and does not automatically convert an existing integration. ZenBlink 2 World Actors, components, Blueprint nodes, emotion enums, presets, and Sequencer tracks may no longer resolve after upgrading.

ZenBlink 3 replaces the previous integration rather than updating it in place. For an established production that does not need ZenBlink 3 features, continuing to use the matching ZenBlink 2 release may be the safest choice. Upgrade only in a project copy or source-control branch.

1. Before Upgrading

1. Back up the complete project or create a dedicated migration branch.
2. Retain the exact ZenBlink 2 plugin package used by the project.
3. Record important ZenBlink settings, selected emotions, target actors, camera focus actors, Blueprint logic, and Sequencer keys.
4. Capture reference screenshots or renders of important characters and shots.
5. Bake any finished ZenBlink 2 animation that must remain visually unchanged.

Do not copy ZenBlink 3 over the ZenBlink 2 plugin directory. Removed v2 files can remain behind and cause duplicate modules, stale assets, or misleading Blueprint references.

2. Remove the ZenBlink 2 Integration

Where practical, remove project references while ZenBlink 2 is still installed:

1. Remove ZenBlink World Actors from affected levels.
2. Remove the old ZenBlink component from MetaHuman Blueprints and level instances.
3. Disconnect Blueprint nodes that depend on ZenBlink 2 classes, enums, structs, interfaces, properties, or functions.
4. Remove obsolete ZenBlink 2 property tracks from Level Sequences after recording their values and timing.
5. Compile and save affected Blueprints, levels, and sequences.
6. Close Unreal Editor.

Never perform this work on the only functioning copy of the v2 project.

3. Install ZenBlink 3 Cleanly

1. Remove the complete ZenBlink 2 plugin directory.
2. Install ZenBlink 3 as a fresh ZenBlink plugin directory.
3. Confirm that only one ZenBlink plugin exists across the project and engine plugin locations.
4. Open the project and enable ZenBlink under Edit > Plugins when required.
5. Restart Unreal Engine when prompted.
6. Review Blueprint compiler and Message Log errors for remaining v2 references.

Use the ZenBlink package built for the project’s Unreal Engine version. ZenBlink 3 supports Unreal Engine 5.6, 5.7, and 5.8.

4. Rebuild the Character Integration

Select the MetaHuman in the World Outliner and click the ZenBlink toolbar icon, or manually add the native ZenBlink Actor Component to the MetaHuman Blueprint. Attach only one ZenBlink component to each character.

Recreate the required setup using the ZenBlink 3 controls:

• Confirm Face Mesh Name resolves the MetaHuman facial skeletal mesh. The standard name is Face.
• Select the required Movement Mode and Eye Mode.
• Reassign Target To Follow and Camera Focus Target actor references.
• Replace emotion enum selections with Emotion Pose assets.
• Re-enable and tune head movement, facial idle, breathing, eye animation, and blinking as required.
• Convert relevant normalized v2 strengths from 0-1 to v3 percentage values where appropriate: 1.0 becomes 100% and 0.5 becomes 50%.

Values are not guaranteed to produce an identical result because the procedural animation system has changed. Treat recorded v2 values as starting points and compare the result against the reference character or render.

Important Changes

• World Actor: Removed. Use the native ZenBlink Actor Component.
• Blueprint-based component: Replaced by the native component.
• Emotion enum: Assign an Emotion Pose asset directly.
• Normalized controls: Many 0-1 values are now user-facing percentages.
• Manual Target mode: Use Follow Target with a movable actor, or Follow Tag.
• Baked head and eye modes: Removed. Use the current modes and baking workflow.
• Head Base Pose: Removed.
• Body movement: Removed.
• Legacy ZenDyn integration: No direct v3 equivalent.
• Existing Sequencer tracks: Recreate them using v3 component properties.

Presets do not store live level references such as Target To Follow or Camera Focus Target. Reassign those references after loading a preset.

5. Rebuild Blueprint and Sequencer Logic

Old serialized property paths do not reconnect automatically, even when a v3 property has a similar display name.

1. Replace references to removed v2 classes, assets, interfaces, structs, and enums.
2. Replace enum-driven emotion logic with writes to Emotion Pose.
3. Recreate movement and eye mode logic using the v3 enums.
4. Recreate required ZenBlink component tracks in Sequencer.
5. Reassign target and camera actors.
6. Compile every dependent Blueprint and resolve errors before testing.

For final animation, use Bake ZenBlink Animations to create animation sequences. Direct baking to Epic’s MetaHuman Control Rigs is experimental and unsupported; bake ZenBlink to animation sequences first, then bake those sequences to the stock Control Rigs when required.

6. Validate or Roll Back

Before approving the migration, confirm:

• All affected Blueprints compile without ZenBlink errors.
• Each character has one ZenBlink component and the face mesh resolves correctly.
• Rig Logic, incoming facial animation, speech, and lipsync remain functional.
• Head movement, targeting, eyes, blinking, emotions, idle, and breathing behave correctly.
• Editor preview, Play In Editor, Sequencer playback, and packaged runtime behavior are correct.
• Baking produces the expected facial curves and head and neck motion.

If the migration cannot be approved, close Unreal Editor and restore the complete pre-migration project and matching ZenBlink 2 plugin. Do not run ZenBlink 2 and ZenBlink 3 together under the same plugin name.

For current ZenBlink 3 setup and controls, see the Quick Start Guide, ZenBlink Component Reference, ZenBlink Target Component, and Zen Emotion.