肢体语言脚本参考

Convai Body Language 模块的完整 API 参考，涵盖控制器、读取结构体、手柄以及所有公共枚举类型。

Convai Body Language 模块中公开类型的完整 API 参考。类型位于 Convai.Modules.BodyLanguage.Components, Convai.Domain.Embodiment.Readings, Convai.Domain.Embodiment.Interfaces，或 Convai.Domain.Embodiment.Semantics，如各类型所注明。跨模块契约（IBodyLanguageSource 以及内部 director）是 internal ，不属于公共接口的一部分。

ConvaiBodyLanguageController

MonoBehaviour — Convai.Modules.BodyLanguage.Components

菜单路径： Convai > 具身化 > 身体语言

约束： DisallowMultipleComponent

属性

属性	类型	描述
当前	BodyLanguageReading	最新发布的肢体语言读数。只读遥测——绝不要构造读数来驱动身体。
表现力	float （get/set）	运行时表达力覆盖， 0–1。设置后会优先于配置文件，直到下一次配置文件热切换。getter 返回有效值：若已设置则返回覆盖值，否则返回最近一次 tick 时配置文件自身解析出的值。

方法

方法	签名	描述
点头	HeadGestureHandle Nod(HeadGestureKind kind, float intensity = 1f)	请求一个脚本化的一次性头部动作。返回的 handle 的 完成 会在程序结束时完成。被拒绝或不可用的请求会返回一个已完成的 handle，并且 IsActive == false ——绝不 null，也绝不抛出异常。
PulseGesture	GestureCueHandle PulseGesture(GestureCue cue)	请求一个脚本化的语义手势提示，其优先级高于自动手势。返回的 handle 的 完成 会在分发结果已知时立即完成。绝不 null，也绝不抛出异常。
TriggerReaction	void TriggerReaction(ReactionKind kind, float intensity = 1f)	一次性、只管触发的身体反应。没有 handle。可安全地在不能 tick 的控制器上调用——静默无操作。
ClearScriptedOverrides	void ClearScriptedOverrides()	完成所有未结的 点头/PulseGesture handle，并将头部动作通道交还给自动 director。幂等。
CaptureSnapshot	void CaptureSnapshot(BodyLanguageSnapshot snapshot)	用调用方拥有、可复用的 BodyLanguageSnapshot 填充完整的实时诊断状态。
CaptureSnapshot	BodyLanguageSnapshot CaptureSnapshot()	对上面方法的分配型便捷重载。

参见 触发手势和反应 用于用法说明以及 HeadGestureRefusal 处理模式。

BodyLanguageReading

Convai.Domain.Embodiment.Readings — 只读结构体

角色当前非语言状态的不可变快照，通过内部 IBodyLanguageSource 契约发布，并在控制器上暴露为 当前。不依赖引擎（没有 UnityEngine 引用）。

属性

属性	类型	描述
DialogueState	DialogueState	策略引擎当前正在作用的对话状态。
PostureOpenness	float	姿态开放度， -1 （封闭/戒备）到 1 （开放），经弹簧平滑后的当前值。
PostureLean	float	矢状面前倾/后仰， -1 （后倾）到 1 （前倾），经弹簧平滑后的当前值。
ShoulderTension	float	肩部/躯干紧张度， -1–1，经弹簧平滑后的当前值。
BreathPhase	float	呼吸振荡器相位，归一化到 [0, 1). 0 为周期起点。
抑制	GesticulationSuppression	会话手势执行器报告的当前手势通道抑制。
HasActiveHeadGesture	bool	当前是否有一个脚本化头部动作程序（点头/摇头/倾斜）正在播放。
ActiveHeadGestureKind	HeadGestureKind	当前正在播放的头部动作程序的种类。只有在 HasActiveHeadGesture 为 true.
LastGestureCueKind	GestureCueKind	最后一次尝试的语义手势提示种类，无论是否被接受或拒绝。
WeightShift	float	姿态 director 当前的髋部侧向重心转移值， -1 （左）到 1 （右）。 0 当重心转移被禁用或尚未排程时。
表现力	float	本 tick 的有效表达力， 0–1.
ActiveReaction	ReactionKind	当前正在播放的一次性身体反应， ReactionKind.None 在空闲时。

静态成员

成员	描述
BodyLanguageReading.None	脱离/静止的读数——没有活动手势，姿态中性， DialogueState.Idle.

HeadGestureHandle

Convai.Modules.BodyLanguage.Components ——密封类

单个脚本化 点头 请求的活动 handle。所有操作都是幂等的，并且绝不抛出异常。

属性

属性	类型	描述
类型	HeadGestureKind	请求的手势种类。
IsActive	bool	该请求是否仍然存活——尚未完成、被取代或被清除。
拒绝原因	HeadGestureRefusal	为何该请求被拒绝，适用于从未存活过的 handle。始终 无 适用于已接受的请求，包括其结束之后。
完成	Task	在头部动作程序结束时完成——自然结束、被取代，或被 ClearScriptedOverrides清除。对于被拒绝的请求，在构造时就已完成。

方法

方法	签名	描述
释放	void Release()	放弃对此请求的关注。可安全地多次调用。

HeadGestureRefusal

Convai.Modules.BodyLanguage.Components — 枚举

为什么一个脚本化头部动作请求没有成为一个活跃程序。

值	Integer	描述
无	0	请求已被接受；该句柄表示一个正在运行的程序。
Busy	1	角色已经在执行一个头部手势，并且后面还排了另一个。该情况是暂时性的——同样的请求在稍后片刻通常会成功。
不可用	2	角色当前完全无法执行头部手势：没有可用的骨架、没有身体语言配置文件，或者该组件被禁用或未在播放。

GestureCueHandle

Convai.Modules.BodyLanguage.Components ——密封类

单个脚本化 PulseGesture 请求的活动 handle。所有操作都是幂等的，并且绝不抛出异常。

属性

属性	类型	描述
类型	GestureCueKind	请求的提示种类。
IsActive	bool	该请求是否仍在等待其分发结果。始终 false 对于被拒绝或被替换的提示会立即如此。
完成	Task	一旦提示的分发结果已知就完成（用于表演则接受，或被拒绝/被替换）。不会跟踪最终生成的片段在视觉上的结束。

方法

方法	签名	描述
释放	void Release()	放弃对此请求的关注。可安全地多次调用。

GestureCue

Convai.Domain.Embodiment.Interfaces — 只读结构体

执行语义手势的单个请求——来自脚本调用、后端动作，或内部反应性的肯定/否定节拍。零分配值类型。

属性

属性	类型	描述
类型	GestureCueKind	所请求手势的语义类别。
强度	float	请求的相对强度/强调程度，通常 0–1+。默认 1.

构造函数

new GestureCue(GestureCueKind.Affirmative)               // kind, intensity defaults to 1
new GestureCue(GestureCueKind.Uncertain, intensity: 0.6f) // kind + intensity

静态成员

成员	描述
GestureCue.None	这个无操作提示： GestureCueKind.None ，强度为零。

GestureCueKind

Convai.Domain.Embodiment.Interfaces — 枚举

脚本化或后端驱动的手势请求可携带的语义类别。

值	Integer	已发货内容	描述
无	0	—	未请求手势。始终被拒绝。
肯定	1	是	一个肯定节拍（例如“是”、同意）。
否定	2	是	一个否定节拍（例如“不是”、不同意）。
问候	3	是	一个问候或告别节拍（例如“嗨”、“拜拜”）。
不确定	4	是	一个不确定/思考节拍（例如“嗯”、沉思）。
强调	5	内敛	一个强调性的伴语手势节拍。已发货内容尚未标记这种类型——保留给未来的伴语手势 director。
节拍	6	内敛	一个通用的节奏性伴语手势节拍。已发货内容尚未标记这种类型。
手掌朝向玩家	7	内敛	一个朝向玩家张开的手掌手势，旨在角色台词中出现第二人称词时触发。已发货内容尚未标记这种类型——在内容为其编写之前，指涉手势 director 完全不工作。
手放胸前	8	内敛	一个手按胸口的手势，旨在第一人称词出现时触发。已发货内容尚未标记这种类型。
指示物体	9	内敛	一个指示/指向手势，旨在注册的场景对象被命名时触发。已发货内容尚未标记这种类型。
列举	10	内敛	一个枚举节拍，旨在序数词或数字词出现时触发。已发货内容尚未标记这种类型。

从保留值构建的提示始终会解析为“无映射”，并回退到头部节拍/姿态脉冲（以及在完整手臂链上，程序化手臂/手）原语——见 触发手势和反应.

ReactionKind

Convai.Domain.Embodiment.Semantics — 枚举

身体语言可请求的一次性身体反应种类。

值	Integer	描述
无	0	无活动反应。
惊讶一颤	1	一次快速受惊：脊柱短暂伸直，肩膀一跳。驱动程序化反应包络。
愉悦弹动	2	一次轻微、愉快的胸部轻弹。驱动程序化反应包络。
倒吸一口气	3	一次快速、锐利的吸气。路由到呼吸系统自身的吸气事件。
叹气	4	一次漫长、深而慢的呼吸。路由到呼吸系统自身的叹息事件。

HeadGestureKind

Convai.Domain.Embodiment.Interfaces — 枚举

身体语言可请求的脚本化一次性头部动作种类。

值	Integer	描述
点头	0	俯仰双点头（下-上-下-停稳）——肯定性的确认。
摇头	1	偏航双交替——否定/拒绝式摇头。
倾斜	2	翻滚式舒缓进入-保持-舒缓退出——好奇/思考式头部倾斜。

ExpressivenessPreset

Convai.Domain.Embodiment.Semantics — 枚举

身体语言的单一表达力旋钮：一个作者设定或运行时的单一参数，可一致地调节整个非语言系统看起来有多大、多频繁以及多丰富。

值	Integer	描述
含蓄	0	最小、克制的动作：小幅度、更慢的节奏，带有可选/由丰富度门控的行为，大多或完全缺失。
自然	1	已发货的默认值：在正常 2 米对话相机距离下可清晰看到的非语言行为，但不会显得像在表演。
富有表现力	2	比 自然.
戏剧化	3	最大幅度、频率和丰富度——一个夸张而具有戏剧感的表演者。
Custom	4	更大、更频繁、更多样的动作。 自定义表现力 配置文件自身的0–1标量（

BodyLanguageSnapshot

Convai.Modules.BodyLanguage.Core.Diagnostics ——密封类

用于 HUD 和测试的、可变且可复用的身体语言运行时状态捕获。只需分配一次，然后通过 ConvaiBodyLanguageController.CaptureSnapshot(BodyLanguageSnapshot).

选定属性

属性	类型	描述
DialogueState	DialogueState	策略引擎在本帧作用的对话状态。
IsInert	bool	模块是否处于静态——不可用的骨架、记录了一次错误、没有每 tick 工作。
HasSpine / HasChest / HasUpperChest / HasShoulders	bool	骨架解析出了哪些躯干骨骼。
ProfileName	string	捕获时有效配置文件的名称。
MasterWeight	float	本 tick 的姿态/呼吸主权重。 0 表示完全不会写入任何骨骼。
BreathPhase / BreathRateCpm / BreathDepth	float	实时呼吸振荡器状态。
HeadGestureIsPlaying / HeadGestureProgress	bool / float	脚本化头部动作是否正在播放，以及其归一化进度。
GesticulationSuppression	GesticulationSuppression	会话手势执行器报告的当前抑制。
LastGestureCueKind / LastGestureCueAccepted	GestureCueKind / bool	最后一次尝试的语义提示，以及它是否被接受。
ReactionFlinch / ReactionBounce	float	当前受惊与弹跳反应包络值。
表现力 / AmplitudeGain / FrequencyGain / RichnessGain	float	已解析的表达力及其三个派生增益。
RecentTrace	List<BodyLanguageTraceEntry>	最近的跟踪日志条目，最旧的在前。

完整字段列表与 ConvaiBodyLanguageController 检查器的 运行时状态 部分绘制的内容一致——见 排查身体语言问题.

下一步

触发手势与反应肢体语言配置文件参考肢体语言故障排查