Face Sync AnimGraph 节点参考

Convai Face Sync AnimGraph 节点所有属性的参考——应用模式、面部 alpha、平滑、饥饿混合以及 blendshape 映射。

该 Convai 面部同步 节点（FAnimNode_ConvaiFaceSync）是一个放置在 AnimGraph 中、位于姿势源和输出姿势之间的动画蓝图节点。它从以下对象读取面部数据： Convai 聊天机器人 同一 Actor 上的组件，应用上/下面部 alpha、可选平滑、starvation 混合，以及可选重映射表，然后将结果曲线值写入输出姿势。

当以下情况时，该节点会自动从所属 Actor 解析其聊天机器人组件： Convai 聊天机器人组件 引脚未设置。所有标记为“默认隐藏引脚”的属性都可通过节点的 详细信息 动画蓝图编辑器中的面板访问。

姿势输入与组件链接

属性	类型	默认值	描述
SourcePose	FPoseLink	—	添加或应用面部曲线的输入姿势。请从 AnimGraph 中前一个节点连接到这里。
ConvaiChatbotComponent	UConvaiChatbotComponent*	nullptr	用于读取面部数据的聊天机器人组件引用。当 nullptr时，节点会自动发现第一个 UConvaiChatbotComponent 在所属 Actor 上的组件。引脚默认显示。

应用模式

属性	类型	默认值	描述
ApplyMode	EConvaiFaceSyncApplyMode	Add	控制曲线值如何写入输出姿势。 Add 将 Convai 值叠加到现有曲线值之上； Override 完全替换现有值。

EConvaiFaceSyncApplyMode 值

值	行为
Add	将 Convai 曲线值添加到源姿势已经包含的任何曲线值上。当身体或待机动画也驱动面部曲线，而你希望将它们混合在一起时使用。
Override	用 Convai 曲线值替换现有曲线值。当 Convai 应作为动画曲线的唯一驱动来源时使用。

面部拆分

属性	类型	默认值	描述
UpperFaceBlendshapeNames	TArray<FName>	[]	被视为上半脸形状（眉毛、眼睛、眼睑）的曲线名称。此列表之外的每条曲线都视为下半脸。引脚默认隐藏。
UpperFaceAlpha	float	0.8	应用于上半脸曲线值的缩放。限制在 [0.0, 1.0]。引脚默认隐藏。
LowerFaceAlpha	float	1.0	应用于下半脸曲线值的缩放。限制在 [0.0, 1.0]。引脚默认隐藏。

当 UpperFaceBlendshapeNames 为空时，所有曲线都接收 LowerFaceAlpha 缩放。

平滑

平滑使用指数移动平均（EMA）。速度值被限制在 [0.0, 1.0] 在编辑器中。 0.0 会产生最大的延迟（每帧该值几乎不会向目标移动）； 1.0 是即时的（不进行平滑，该值在一帧内到达目标）。在 0.5 和 60 fps 下，每条曲线每帧大约向目标移动 50%。实用起始值： 0.3–0.5 用于平滑且响应灵敏的下半脸； 0.1–0.2 用于更克制的上半脸。

属性	类型	默认值	描述
bEnableLowerFaceSmoothing	bool	false	为下半脸曲线启用指数移动平均平滑。
LowerFaceSmoothingSpeed	float	1.0	下半脸平滑的 EMA 速度。限制在 [0.0, 1.0] 在编辑器中： 0.0 = 最大延迟， 1.0 = 即时。仅当 bEnableLowerFaceSmoothing 为 true。引脚默认隐藏。
bEnableUpperFaceSmoothing	bool	false	为上半脸曲线启用指数移动平均平滑。
UpperFaceSmoothingSpeed	float	1.0	上半脸平滑的 EMA 速度。限制在 [0.0, 1.0] 在编辑器中： 0.0 = 最大延迟， 1.0 = 即时。仅当 bEnableUpperFaceSmoothing 为 true。引脚默认隐藏。

缓冲耗尽混合

当口型同步缓冲区的帧耗尽时——例如在说话轮次之间或第一帧到达之前——节点会将曲线贡献混合到零。 当帧再次可用时，它会重新混入。这可以防止面部突然跳回中性再跳回来。

属性	类型	默认值	描述
StarvationBlendInDuration	float	0.1	将曲线贡献从 0 到 1 在帧变为可用时进行混合。设置为 0 可实现即时过渡。引脚默认隐藏。
StarvationBlendOutDuration	float	0.8	将曲线贡献从 1 到 0 在缓冲区为空时。设置为 0 可实现即时过渡。引脚默认隐藏。

这两个值都按恒定速率生效。在过渡中途反向所需时间会按比例少于完整过渡。

Blendshape 映射

属性	类型	默认值	描述
BlendshapeMapping	TMap<FName, FConvaiBlendshapeParameters>	{}	可选的重映射表。键为来自 Convai 的源曲线名称；值为一个 FConvaiBlendshapeParameters 结构体，用于定义目标曲线名称、每项乘数、偏移、限制以及可选覆盖。为空时，曲线按 1:1 应用，不进行重映射。引脚默认隐藏。
GlobalMultiplier	float	1.0	应用于所有映射曲线值的乘数，除非 IgnoreGlobalModifiers 在该条目上已设置。引脚默认隐藏。
GlobalOffset	float	0.0	添加到所有映射曲线值上的偏移，除非 IgnoreGlobalModifiers 在该条目上已设置。引脚默认隐藏。

FConvaiBlendshapeParameters 字段

FConvaiBlendshapeParameters 定义每个条目的映射行为。所有字段均可在蓝图中读/写。

字段	类型	默认值	描述
TargetNames	TArray<FName>	[]	Skeletal Mesh 上用于写入源值的一个或多个目标曲线名称。一条源曲线可分发到多个目标。
Multiplyer	float	1.0	在以下操作之前应用于每项的缩放： GlobalMultiplier （除非 IgnoreGlobalModifiers 为 true）。注意：源中的字段名包含一个拼写错误——它是 Multiplyer，而不是 Multiplier.
Offset	float	0.0	每项在缩放后添加的偏移。
UseOverrideValue	bool	false	当 true，则曲线设置为 OverrideValue ，而不管输入数据如何。适用于将曲线固定到某个值。
OverrideValue	float	0.0	当 UseOverrideValue 为 true.
IgnoreGlobalModifiers	bool	false	当 true, GlobalMultiplier 和 GlobalOffset 未应用于此条目时使用的固定值。
ClampMinValue	float	0.0	在所有缩放和偏移之后，曲线允许达到的最小值。
ClampMaxValue	float	1.0	在所有缩放和偏移之后，曲线允许达到的最大值。

命令行覆盖

下面列出的可调属性可在启动时通过传入一个 -LipSyncAnim* 标志来覆盖。覆盖会在每个 PIE 会话中于 Initialize_AnyThread 中解析一次，并优先于在动画蓝图中编写的值。命令行中未设置的标志将回退到 UPROPERTY 值。

标志	类型	示例
-LipSyncAnimUpperFaceAlpha	float	-LipSyncAnimUpperFaceAlpha=0.5
-LipSyncAnimLowerFaceAlpha	float	-LipSyncAnimLowerFaceAlpha=0.8
-LipSyncAnimStarvationBlendInDuration	float	-LipSyncAnimStarvationBlendInDuration=0.05
-LipSyncAnimStarvationBlendOutDuration	float	-LipSyncAnimStarvationBlendOutDuration=1.2
-LipSyncAnimGlobalMultiplier	float	-LipSyncAnimGlobalMultiplier=1.2
-LipSyncAnimGlobalOffset	float	-LipSyncAnimGlobalOffset=0.0
-LipSyncAnimLowerFaceSmoothingSpeed	float	-LipSyncAnimLowerFaceSmoothingSpeed=0.4
-LipSyncAnimUpperFaceSmoothingSpeed	float	-LipSyncAnimUpperFaceSmoothingSpeed=0.2
-LipSyncAnimEnableLowerFaceSmoothing	bool (1/true)	-LipSyncAnimEnableLowerFaceSmoothing=1
-LipSyncAnimEnableUpperFaceSmoothing	bool (1/true)	-LipSyncAnimEnableUpperFaceSmoothing=1
-LipSyncAnimBypassSmoothing	bool (1/true)	-LipSyncAnimBypassSmoothing=1
-LipSyncAnimBypassStarvationBlend	bool (1/true)	-LipSyncAnimBypassStarvationBlend=1
-LipSyncAnimApplyMode	Add 或 Override	-LipSyncAnimApplyMode=Override

命令行覆盖按进程生效。它们可用于在开发期间调整口型同步行为，而无需编辑和重新编译动画蓝图。它们不会在编辑器重启后保留。

相关参考

Face Sync 组件参考口型同步使用示例