身体动画脚本参考

Convai Body Animation 公共 API 参考，包括控制器、动作与指向句柄以及移动类型。

Convai Body Animation 中公共类型的完整参考。类型位于 Convai.Modules.BodyAnimation, Convai.Modules.BodyAnimation.Components, Convai.Modules.BodyAnimation.Data, Convai.Modules.BodyAnimation.Core.Locomotion, Convai.Modules.BodyAnimation.Core.Diagnostics，以及 Convai.Runtime.Embodiment 命名空间中，如每个类型所注明。

ConvaiBodyAnimationController

ConvaiCharacterModule<ConvaiBodyAnimationProfile>, MonoBehaviour — Convai.Modules.BodyAnimation.Components

菜单路径： Convai/Embodiment/Body Animation. DisallowMultipleComponent.

Body Animation 系统的组合根：构建 PlayableGraph 于 Humanoid 上 Animator，运行层堆栈，并公开动作、指向和行走同步。可通过 GetComponent<ConvaiBodyAnimationController>() 在角色上获取。

属性

属性	类型	描述
AnimationSet	ConvaiBodyAnimationSet	该角色实际播放的动画内容。 null 表示没有内容——角色静止不动。
配置	ConvaiBodyAnimationConfig	该角色实际运行的调优配置。绝不会 null ——回退到内置默认值。
FeatureAvailability	BodyAnimationFeatureAvailability	在已构建的集合上，哪些默认启用的功能实际生效，哪些虽已启用但没有匹配内容。
IsAnimationSetSwapPending	bool	true 当一个 SetAnimationSet 请求已排队但尚未开始其交叉淡入淡出交接时。
IsRuntimeBuilt	bool	动画图已构建并准备好接收调用。
TargetAnimator	Animator	该 Animator 图输出到的对象，在构建时解析。
CurrentActionName	string	当前正在播放的动作名称；若无则为空。
IsReorienting	bool	当前是否正在播放动画化的面向转身（原地转身）。

方法

方法	签名	描述
SetAnimationSet	void SetAnimationSet(ConvaiBodyAnimationSet set)	在运行时切换动画内容。正在运行的控制器会将图交接延后，直到安全的空闲边界。
SetConfig	void SetConfig(ConvaiBodyAnimationConfig config)	在运行时切换运行时调优；进行中的手势绝不会被打断。一个 null 配置会被拒绝。
SetConversationAnchor	void SetConversationAnchor(Transform anchor)	覆盖锚点的社交间距、亲近表达和环境抑制，将其视为“该角色正在与之交谈的人”。
ClearConversationAnchor	void ClearConversationAnchor()	清除通过 SetConversationAnchor设置的锚点；解析会回退到 Camera.main，然后是第一个启用的摄像机。
PlayAction	BodyAnimationActionHandle PlayAction(string nameOrAlias, ActionPlayOptions options = default)	播放一个命名的动作/手势。从不返回 null — 检查 Failed/FailureReason 在返回的句柄上。
StopAction	bool StopAction()	平滑停止当前动作；若已编排，条目的结尾段会播放。
StopActionImmediate	bool StopActionImmediate(float blendOutSeconds = -1f)	立即停止当前动作，并将其交叉淡出。
PlayActionAt	PlayActionAtHandle PlayActionAt(Transform anchor, string actionNameOrAlias)	走向 锚点，进行根部对齐，然后播放动作。从不返回 null.
PlayActionAt	PlayActionAtHandle PlayActionAt(Transform anchor, string actionNameOrAlias, ActionAnchorOptions anchorOptions, ActionPlayOptions playOptions = default)	同上，但可显式指定锚点和播放调优。
PointAt	BodyAnimationPointingHandle PointAt(Vector3 worldPosition, float holdSeconds = -1f)	指向一个固定的世界位置。从不返回 null.
PointAt	BodyAnimationPointingHandle PointAt(Transform target, float holdSeconds = -1f)	指向一个（移动的）Transform，在保持期间重新瞄准。
PointAt	BodyAnimationPointingHandle PointAt(Transform target, in PointingPlayOptions options)	同上，但带播放微调（速度、混合时长、释放样式）。
StopPointing	void StopPointing()	释放当前的指向保持；下臂尾段仍会播放。
StopPointingImmediate	void StopPointingImmediate(float blendOutSeconds = -1f)	立即停止当前指向保持并将其交叉淡出，跳过下臂尾段。
FaceTowards	bool FaceTowards(Vector3 worldDirection, string reason = "FaceTowards")	使用动画化的原地转身系列让角色旋转以面向某个方向。返回 false 当请求无法被满足时。
CaptureSnapshot	void CaptureSnapshot(BodyAnimationSnapshot snapshot)	填充 snapshot ，内容为实时动画状态，并复用其列表。
CaptureSnapshot	BodyAnimationSnapshot CaptureSnapshot()	带分配的便捷重载，会创建并填充一个新的 BodyAnimationSnapshot.

事件

事件	签名	在以下情况时触发
StateChanged	event Action<AnimStateChange>	每一次动画转换，与跟踪日志一致。
ActionEvent	event Action<BodyAnimationActionEvent>	每个动作/手势生命周期阶段（已开始、即将结束、已完成、被中断、被拒绝）。
RuntimeReady	event Action	在运行时完全可用后，每次成功构建时触发一次。一个处理程序如果在其中调用 PlayAction/PointAt/PlayActionAt 它，会立即成功——这是文档中“先订阅再调用”的模式，适用于必须命中的调用。

AnimStateChange

只读结构体—— Convai.Modules.BodyAnimation

一次动画转换，如通过 ConvaiBodyAnimationController.StateChanged.

属性	类型	描述
Layer	string	发生转换的层，例如 "Locomotion", "Talk", "Action".
From	string	转换前的状态标签。
To	string	转换后的状态标签。
Clip	string	转换落到的剪辑。若只是纯权重淡出，可为空。
FadeSeconds	float	交叉淡入淡出时长（秒）。
原因	string	人类可读的触发原因，例如 "speaking started" 或 "yaw error 142°".

BodyAnimationActionEvent

只读结构体—— Convai.Modules.BodyAnimation

一次动作生命周期通知，通过 ConvaiBodyAnimationController.ActionEvent.

属性	类型	描述
ActionName	string	该事件所描述的动作名称。
Phase	BodyAnimationActionPhase	该事件报告的生命周期阶段。

BodyAnimationActionPhase 值： Started (0), Ending (1), 已完成 (2), Interrupted (3), Rejected (4).

BodyAnimationActionHandle

密封类—— Convai.Modules.BodyAnimation

正在运行的动作的实时句柄，由 PlayAction.

成员	类型	描述
ActionName	string	请求的名称或别名。
Failed	bool	此句柄是否代表一个从未开始的请求。
FailureReason	string	请求失败的原因；当 Failed 为 false.
IsDone	bool	true 在动作完全结束或被中断之后。
完成	Task<bool>	在以下情况下解析 true 播放完成时， false 被中断时。
Stop()	void	请求平滑停止；若已编排，条目的结尾段会播放。可安全重复调用。
StopImmediate(float blendOutSeconds = -1f)	void	立即停止并将动作交叉淡出，跳过剩余链或结尾段。 完成 解析为 false.

PlayActionAtHandle

密封类—— Convai.Modules.BodyAnimation

请求的实时句柄， PlayActionAt 请求：移动到锚点 → 根部对齐 → 播放动作。

成员	类型	描述
ActionName	string	请求的动作名称。
Phase	PlayActionAtPhase	请求的当前阶段。
Failed	bool	此句柄是否代表一个从未开始的请求。
FailureReason	string	请求失败的原因；当 Failed 为 false.
IsDone	bool	true 在请求完成或被取消之后。
完成	Task<bool>	在以下情况下解析 true 当动作播放完成时， false 当被取消时。
Cancel()	void	取消当前所在位置的请求。幂等，可在任何阶段安全调用。

PlayActionAtPhase 值： Approaching (0)——走向锚点的接近点； Aligning (1)——以根部插值精确对齐； PlayingAction (2)——锚定的动作本身正在播放； 已完成 (3)——自然结束； 已取消 (4)——在结束前被取消或失败。

BodyAnimationPointingHandle

密封类—— Convai.Modules.BodyAnimation

指向手势的实时句柄，由每个 PointAt 重载返回。

成员	类型	描述
Failed	bool	此句柄是否代表一个从未开始的请求。
FailureReason	string	请求失败的原因；当 Failed 为 false.
IsDone	bool	true 在指向手势完全结束后（手臂放下）。
完成	Task	在手势完全结束后解析。
Release()	void	现在结束保持；下臂尾段会在完成前播放。
ReleaseImmediate(float blendOutSeconds = -1f)	void	立即停止并将姿势交叉淡出，跳过下臂尾段。
SetSpeed(float speed)	void	实时调整正在运行手势的抬起/放下速度。保持期间无操作。

ActionPlayOptions

结构体—— Convai.Modules.BodyAnimation

针对以下内容的可选播放微调 ConvaiBodyAnimationController.PlayAction.

字段	类型	描述
SpeedMultiplier	float	在条目速度之上的播放速度乘数。 <= 0 = 条目默认值。
HoldSeconds	float	对于保持直到停止的动作：在主循环运行这么多秒后自动请求停止。 <= 0 = 保持直到停止。
FadeInSeconds	float	层混入时长覆盖。 <= 0 = 条目覆盖 / 配置默认值。
FadeOutSeconds	float	层混出时长覆盖；也用于 StopActionImmediate. <= 0 = 条目 / 配置默认值。
WeightMultiplier	float	动作层权重乘数。 <= 0 保留现有行为。

PointingPlayOptions

结构体—— Convai.Modules.BodyAnimation

针对以下内容的可选播放微调 ConvaiBodyAnimationController.PointAt.

字段	类型	描述
Speed	float	抬起/放下速度乘数。 <= 0 = 原生（1）。保持本身不受影响。
HoldSeconds	float	在顶点保持的秒数。 <= 0 = 保持直到释放。
BlendInSeconds	float	层混入时长。 <= 0 = 配置 PointingFadeSeconds.
BlendOutSeconds	float	层混出时长。 <= 0 = 配置 PointingFadeSeconds.
ReleaseStyle	PointingReleaseStyle	一次经过的 HoldSeconds 自动释放会做什么。
WeightMultiplier	float	指向层权重乘数。 <= 0 保留现有行为。

PointingPlayOptions.Default 返回 Speed = 1, HoldSeconds = -1, BlendInSeconds = -1, BlendOutSeconds = -1, ReleaseStyle = PointingReleaseStyle.PlayTail, WeightMultiplier = 1.

PointingReleaseStyle 值： PlayTail (0)——在层淡出前先播放下臂尾段（默认，原始行为）； Blend (1)——立即将当前姿势交叉淡出，跳过下臂尾段。

BodyAnimationSnapshot

密封类—— Convai.Modules.BodyAnimation

Body animation 系统的完整、低分配视图：单帧中的层权重和状态、对话/行走输入，以及最近的转换跟踪。可通过 ConvaiBodyAnimationController.CaptureSnapshot 填充——这是按需诊断，不是每帧游戏代码。

字段	类型	描述
Owner	string	捕获此快照所对应的角色名称。
SetName	string	活动动画集的显示名称， "(none)" ，当未设置时。
DialogueState	DialogueState	本帧读取到的对话状态。
SpeechEnergy	float	本帧读取到的实时语音能量。
AgentSpeed	float	NavMeshAgent 速度（m/s）。 0 直到存在一个行走组件。
AnimationSpeed	float	在速率变形后应用于行走的有效动画循环速度（m/s）——用于脚滑检查。
LocomotionState	string	行走状态机标签，例如 "Idle", "Move", "Stop:LF".
DesiredSpeed	float	当前移动的指令行进速度。
RemainingDistance	float	剩余行进距离。
RateWarp	float	应用于行走的当前播放速率变形。
GraphPlayableCount	int	中的实时 playable 数量 PlayableGraph.
Layers	List<BodyAnimationLayerSnapshot>	层堆栈中每个端口的逐层状态（名称、活动状态、剪辑、权重、遮罩、拥有者）。
RecentTrace	List<AnimTraceEntry>	从跟踪环形缓冲区复制的最近转换日志，最旧的在前。

Clear() 将每个字段重置为其脱离状态的默认值。 BodyAnimationLayerSnapshot 是一个公开结构体，携带 Name, State, Clip, Weight, DesiredWeight, EnvelopeWeight, ArbiterTargetWeight, FinalWeight, Owner, 掩码, Additive，以及 NormalizedTime ，用于一个层端口。

BodyAnimationFeatureAvailability

只读结构体—— Convai.Modules.BodyAnimation.Data

在构建时快照给定动画集与配置组合实际能够执行的内容，通过 ConvaiBodyAnimationController.FeatureAvailability公开。可直接用静态 Compute 方法在没有实时运行时的编辑模式读取。

属性	类型	描述
BeatGestures	BodyAnimationFeatureState	节拍手势切换是否开启，以及该集合是否包含 节拍/强调标记的内容。
ReferentialGestures	BodyAnimationFeatureState	指示性手势切换是否开启，以及该集合是否包含带标记的内容。无论哪种方式都总能解析——通过已编排的剪辑或同伴表演者。
AmbientActivities	BodyAnimationFeatureState	环境活动切换是否开启，以及该集合是否包含一个 Ambient标记的动作。
GestureBrackets	BodyAnimationFeatureState	Talk/Listen/Think 池中是否有任何一个编排了开场或结尾剪辑。没有切换——只要存在内容就总会尝试。
MovingTalkAdditive	BodyAnimationFeatureState	是否 MovingTalkMode 为 自动 且该集合编排了一个 Additive Clip。除模式本身外没有其他切换。
CueTaggedActions	BodyAnimationFeatureState	该集合是否编排了任何标记为 肯定, 否定, 问候，或 不确定的动作。没有切换——总会尝试。
IdleVariantCount	int	可播放的待机变体数量。
TalkVariantCount	int	可播放的 Talk 池变体数量。
HasEmotionAffinities	bool	任何待机或说话变体是否带有情绪亲和性。

BodyAnimationFeatureState 从其基类中 Enabled, HasContent，以及派生的 IsEffective, IsEnabledWithoutContent，以及 IsContentWithoutEnable 属性。 Compute(ConvaiBodyAnimationSet set, ConvaiBodyAnimationConfig config) 当任一参数为 null.

IConvaiLocomotionSource

接口 — Convai.Modules.BodyAnimation.Core.Locomotion

Body Animation 读取的最少公共移动数据，来自一个 locomotion 提供者。由以下对象实现： ConvaiNavMeshLocomotion；请在一个上实现它 MonoBehaviour 分配给控制器的 Locomotion Provider 覆写 字段，以从自定义移动系统驱动动画同步。

成员	类型	描述
IsMoving	bool	角色当前是否正在位移。
PathPending	bool	路径是否仍在计算中。
Speed	float	实时水平速度（m/s）。
DesiredSpeed	float	当前移动的指令旅行速度（m/s）。
RemainingDistance	float	剩余旅行距离， 0 在空闲时。
SignedAngleToSteering	float	从角色前向到当前转向方向的带符号偏航角（度）。
Destination	Vector3	移动时的当前目的地。
MoveEnded	事件 Action<bool>	在移动结束时触发。 true = 到达目的地， false = 已取消。

三个可选接口 — IConvaiLocomotionCommands, IConvaiManagedLocomotion, IConvaiAnchorAlignment — 当存在于同一组件上时会被发现，每个都会解锁一项额外能力。请参见 配置移动 了解各自新增了什么。

ConvaiTravelIntent

MonoBehaviour — Convai.Runtime.Embodiment

菜单路径： Convai/Embodiment/Travel Intent. DisallowMultipleComponent.

说明角色正在去往哪里，因此同伴——例如在行走时注视路径的 Convai Gaze——在它旅行时可以表现得不同。当角色实际移动的瞬间会自动提供；只有在要更改检测阈值或关闭自动检测时才手动添加。

属性

属性	类型	描述
IsTraveling	bool	角色现在是否正在前往某处。
HasSubject	bool	是否已有任何内容声明当前旅程的主题。
来源	TravelSource	当前读取来源： NotTraveling, Reported, Locomotion，或 Observed.
TravelReportTimeoutSeconds	float	一条已报告的旅程在未重复报告的情况下保持有效的时长。

方法

方法	签名	描述
ReportTravel	void ReportTravel(Vector3 worldDirection, float speed01)	声明角色正在朝以下方向旅行： worldDirection 中声明所需权限，位置为 speed01 （0..1 表示全部力度）。在移动持续的每一帧都调用。
ReportTravel	void ReportTravel(Vector3 worldDirection, float speed01, float remainingDistance)	同上，但带有已知的剩余距离。
ReportTravelTo	void ReportTravelTo(Vector3 destination, float speed01)	便捷方式：报告朝向 destination 的旅行，并在一次调用中将其设为主题。
ClearTravel	void ClearTravel()	立即结束已报告的旅程，而不必等待其过期。
SetSubject	void SetSubject(Transform subject)	声明这段旅程是关于 subject 的——会从同伴那里获得定期关注。
SetSubject	void SetSubject(Vector3 worldPosition)	声明这段旅程是关于一个固定地点的。
ClearSubject	void ClearSubject()	忘记这段旅程是关于什么的。角色仍会继续看路。

AnimTraceVerbosity

枚举 — Convai.Modules.BodyAnimation.Core.Diagnostics

用于身体动画诊断的详细程度级别，设置于 ConvaiBodyAnimationConfig.TraceVerbosity。每个级别都包含其下方的所有内容。

值	Integer	描述
关闭	0	不输出跟踪日志。警告和错误仍会记录。这是随包发布的默认值。
State	1	状态机转换、层所有权变更、动作生命周期、动画片段选择以及启动功能摘要。
详细信息	2	添加选择器决策、带权重的变体抽取、速度扭曲钳制，以及执行器开始/结束标记。
火力全开	3	添加按节流的逐 tick 层权重和混合位置转储。信息极其冗长；仅用于短时间调试会话。

相关参考

身体动画配置参考播放动作和手势配置移动