具身化脚本参考

Convai 具身化脚本接口参考，包括角色上下文、模块基类、骨架绑定和共享枚举。

Unity 脚本可以直接使用的公共 embodiment 类型参考： EmbodimentContext，则 ConvaiCharacterModule<TProfile> 自定义模块的基类， StandardRigBinding, ConvaiTravelIntent, ModuleIds，以及共享的 CharacterDemeanor, StandardBone, StandardBlendshape，以及 RigConvention 枚举。跨模块契约（例如 IGazeSource 和 IEmotionStateSource ）属于内部实现，不在此表面 API 范围内——请改为阅读各模块自己的控制器参考文档。

EmbodimentContext

EmbodimentContext (密封类：MonoBehaviour）是角色作用域的组合根，embodiment 模块会解析它以访问共享基础设施。Convai 会自动将其添加到角色上——它携带一个隐藏的 [AddComponentMenu("")] ，并不是需要你手动添加的东西。

静态解析

成员	签名	描述
TryResolve	static bool TryResolve(Component origin, out EmbodimentContext context)	在 origin 的角色根上定位或创建一个上下文。若 false 时 origin 不在 ConvaiCharacter下方，则静默返回
TryResolveFor	static bool TryResolveFor(Component owner, out EmbodimentContext context)	相同的解析逻辑，但在无法解析出上下文时会记录一条标明 owner 的设置错误。适用于在没有角色时无法工作的组件。

属性

属性	类型	描述
CharacterRoot	Transform	角色根 Transform。
EventHub	IEventHub	用于监听领域事件的事件总线。
日志记录器	ILogger	用于结构化诊断的日志记录器。若尚未注入，可能为 null 。
RigBinding	IStandardRigBinding	角色的 rig 绑定抽象（语义骨骼与 blendshape）。
Character	ConvaiCharacter	拥有该角色的对象（如果此层级中存在）。

事件

事件	签名	在以下情况时触发
RigBindingChanged	event Action<IStandardRigBinding>	语义 rig 绑定在运行时被重建或替换。缓存了骨骼或网格引用的模块应重新解析它们。
EmbodimentConfigurationChanged	event Action	embodiment 模块配置在运行时已更新——例如应用了一个预设。
DependenciesPopulated	event Action	诸如 EventHub、tick 调度器以及动画器基础设施等仅运行时依赖项会变为可用。

Tickable

成员	签名	描述
RegisterTickable	bool RegisterTickable(IEmbodimentTickable tickable)	驱动 tickable 从此角色的 embodiment 调度器执行，而不是使用 Unity 的按组件 Update，因此它的写入会按已声明的顺序相对于 Convai 自身的写入生效。请从 OnEnable调用。重复注册同一实例不会产生任何效果。返回 false ，表示当前还没有可加入的调度器——在 Play 模式之外这是正常情况。
UnregisterTickable	void UnregisterTickable(IEmbodimentTickable tickable)	停止驱动 tickable。请从 OnDisable调用。即使该 tickable 从未注册过，或者调度器已经消失，调用也安全。

ConvaiCharacterModule<TProfile>

ConvaiCharacterModule<TProfile> (抽象类：MonoBehaviour, [ExecuteAlways]）是每个 embodiment 模块都要继承的基类—— ConvaiGazeController, ConvaiBodyAnimationController, ConvaiBodyLanguageController, ConvaiConversationFlowController，以及 ConvaiEmotionController 所有模块都扩展自它。 TProfile 是 ScriptableObject 该模块拥有的 profile 类型。编写你自己的此类型子类，就可以构建一个自定义 embodiment 模块，使其参与与随附模块相同的上下文解析、profile 接收器注册和 tick 生命周期。

受保护成员

成员	类型	描述
上下文	EmbodimentContext	为该角色解析得到的上下文。设置一次， OnEnable 成功后。
EffectiveProfile	TProfile	已创作的 profile 资源（如果分配了的话），否则为来自 DefaultProfileFactory. null 之前 Awake 的运行时默认值。
ProfileModuleId	abstract string	此子类向 profile 接收器系统报告的模块 ID。当模块是五个随附模块之一时，请使用一个 ModuleIds 常量；否则使用你自己稳定的字符串。
DefaultProfileFactory	abstract Func<TProfile>	在未分配资源时创建运行时默认 profile 的工厂。

方法

方法	签名	描述
OnProfileApplied	virtual void OnProfileApplied(TProfile newProfile)	在 profile 槽位更新后调用，例如由预设触发。重写它以重置状态，或重新解析依赖 profile 的绑定。
ProvideService	void ProvideService<TContract>(TContract service)	将此组件发布为该角色的 TContract 提供者，并跟踪该注册以便在 OnDisable.
ContributeService	void ContributeService<TContract>(TContract service)	将此组件作为扇出契约（每个角色可对应多个观察者）的贡献者添加进去，跟踪方式与 ProvideService.
ReleaseProvidedServices	void ReleaseProvidedServices()	撤销此组件发布的每一个契约。由基类中的 OnDisable调用。重写 OnDisable 时必须调用 base.OnDisable()，否则其注册会超出它本身的生命周期。

Awake, OnEnable, OnDisable，以及 OnDestroy 为 virtual 并在基类实现中处理上下文解析与 profile 接收器注册——重写任一方法时都要调用基类方法。

StandardRigBinding

StandardRigBinding (密封类：MonoBehaviour, IStandardRigBinding, [AddComponentMenu("Convai/Embodiment/Character Rig")]）会检查角色层级，并据此解析语义骨骼和 blendshape 查找。有关检测与置信度如何工作，请参见 角色骨骼设置 。

属性

属性	类型	描述
Root	Transform	如果角色有 Animator，则为其 Transform；否则为此组件自身的 Transform。
FacialMeshes	IReadOnlyList<SkinnedMeshRenderer>	用于 blendshape 解析的网格。
DetectedConvention	RigConvention	为该 rig 检测到的 blendshape 命名约定，或者在设置了手动覆盖时使用手动覆盖。
CustomConventionMap	CustomRigConventionMap	自定义的语义到 blendshape 映射，用于当 DetectedConvention 为 Custom.
DetectionConfidence	float	上一次检测过程的置信度，范围为 0 到 1. 1 当手动设置了约定覆盖时。

方法

方法	签名	描述
Rebuild	void Rebuild()	重新扫描层级，并重建骨骼与 blendshape 的解析表。当服装发生变化、网格被替换，或在运行时应用了约定覆盖时调用。
TryGetBone	bool TryGetBone(StandardBone semantic, out Transform bone)	解析一个语义骨骼。当找不到该骨骼时，会在组件生命周期内仅记录一次警告。
TryGetBlendshape	bool TryGetBlendshape(StandardBlendshape semantic, out SkinnedMeshRenderer mesh, out int blendshapeIndex)	解析一个语义 blendshape。当找不到时，会在组件生命周期内仅记录一次警告。

ConvaiTravelIntent

ConvaiTravelIntent (密封类：MonoBehaviour, IEmbodimentTickable, ITravelIntentSource, [AddComponentMenu("Convai/Embodiment/Travel Intent")]）用于报告角色正要去哪里，因此像 Gaze 这样的模块可以在角色行走时观察道路，而不是一直盯着目的地。

你通常不需要手动添加此组件——一旦角色开始移动，它就会自动提供，并在角色消失时一并消失。只有在想更改运动检测阈值或关闭自动检测时，才手动添加它。

Travel 从三个来源解析，优先级从高到低：通过 ReportTravel 或 ReportTravelTo的显式报告、来自 ConvaiNavMeshLocomotion 的推送（如果角色有的话），或 Convai 直接在角色 Transform 上观察到的移动。请在你自己的移动代码中调用 ReportTravel （或 ReportTravelTo）——例如一个 NavMeshAgent驱动的移动器、一个 CharacterController、根运动或 tween——这样即使角色的移动不是由 ConvaiNavMeshLocomotion 驱动，它在移动时也仍会正确转头并调整步态。如果不重复报告，报告会在 TravelReportTimeoutSeconds 后过期，因此停止报告的调用方不会让角色永远处于旅行状态。

属性

属性	类型	描述
IsTraveling	bool	角色现在是否正在前往某处。
HasSubject	bool	是否有任何内容声明了当前旅程的主题。没有主题时，角色会看着路，但心里没有目的地。
来源	TravelSource	当前 travel 读数的来源： 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 的 travel，并在一次调用中将其设为 travel 主题。
ClearTravel	void ClearTravel()	立即结束已报告的旅程，而不必等待其过期。
SetSubject	void SetSubject(Transform subject)	声明这段旅程是关于 subject ——例如，被跟随的人。这就是它为何会定期朝它瞥一眼。
SetSubject	void SetSubject(Vector3 worldPosition)	声明这段旅程是关于一个固定地点的。
ClearSubject	void ClearSubject()	忘记这段旅程是关于什么的。角色仍会继续看路。

ModuleIds

ModuleIds (静态类）保存了 embodiment 模块在向 EmbodimentContext注册 profile 时使用的规范路由键，以及一个 ConvaiEmbodimentPreset slot 用来定位模块的键。

常量	值	路由到
身体动画	convai.body-animation	ConvaiBodyAnimationController
BodyLanguage	convai.body-language	ConvaiBodyLanguageController
对话流程	convai.conversation-flow	ConvaiConversationFlowController
情绪	convai.emotion	ConvaiEmotionController
注视	convai.gaze	ConvaiGazeController

CharacterDemeanor

CharacterDemeanor 是 Emotion、Body Animation 和 Body Language 编辑器共用的一套创作词汇，这样在每个模块的资源上选择相同的 demeanor 就能描述同一个连贯的角色。demeanor 只用于创作：应用它时只会把普通值写入正在编辑的资源，而运行时没有任何东西会读取这个枚举。每个模块都会按自己的语义来解释同一个词。

值	编号	描述
沉稳	0	平静而均衡——接待员、职员、向导。
温暖	1	亲和且易读。当角色被刻意赋予个性时，这是默认值。
充满活力	2	反应大、速度快——主持人、导游、主播。
内敛	3	几乎不表现任何情绪——警卫、司仪。

StandardBone

StandardBone 识别角色 rig 骨骼的 embodiment 模块可以通过 StandardRigBinding.TryGetBone解析这些骨骼，而不依赖底层 rig 的命名约定。

值	编号	值	编号
Hips	0	LeftShoulder	8
脊柱	1	RightShoulder	9
Chest	2	LeftUpperArm	10
UpperChest	3	RightUpperArm	11
Neck	4	LeftUpperLeg	12
头部	5	LeftLowerLeg	13
LeftEye	6	LeftFoot	14
RightEye	7	RightUpperLeg	15
		RightLowerLeg	16
		RightFoot	17

StandardBlendshape

StandardBlendshape 识别角色面部 blendshape 的 embodiment 模块可以通过 StandardRigBinding.TryGetBlendshape解析这些 blendshape。值遵循 ARKit 52-blendshape 命名约定；其他约定（Reallusion CC3、MetaHuman、Custom）都会映射到这些相同的语义名称上。并非每个 rig 都提供每个 blendshape——模块必须能够优雅地处理 TryGetBlendshape 返回 false 以及无操作。

区域	数值
眼部	EyeBlinkLeft, EyeBlinkRight, EyeLookDownLeft, EyeLookDownRight, EyeLookInLeft, EyeLookInRight, EyeLookOutLeft, EyeLookOutRight, EyeLookUpLeft, EyeLookUpRight, EyeSquintLeft, EyeSquintRight, EyeWideLeft, EyeWideRight, EyeUpperLidDownLeft, EyeUpperLidDownRight, EyeUpperLidUpLeft, EyeUpperLidUpRight, EyeLowerLidUpLeft, EyeLowerLidUpRight
眉部	BrowDownLeft, BrowDownRight, BrowInnerUp, BrowOuterUpLeft, BrowOuterUpRight
Cheek / Nose	CheekPuff, CheekSquintLeft, CheekSquintRight, NoseSneerLeft, NoseSneerRight
下颌	JawForward, JawLeft, JawRight, JawOpen
嘴部	MouthClose, MouthFunnel, MouthPucker, MouthLeft, MouthRight, MouthSmileLeft, MouthSmileRight, MouthFrownLeft, MouthFrownRight, MouthDimpleLeft, MouthDimpleRight, MouthStretchLeft, MouthStretchRight, MouthRollLower, MouthRollUpper, MouthShrugLower, MouthShrugUpper, MouthPressLeft, MouthPressRight, MouthLowerDownLeft, MouthLowerDownRight, MouthUpperUpLeft, MouthUpperUpRight
舌头	TongueOut

RigConvention

RigConvention 识别 blendshape 和骨骼命名约定 StandardRigBinding ，适用于角色面部 rig 检测到的约定，或作为覆盖手动指定的约定。

值	编号	描述
未知	0	检测尚未运行，或者该 rig 未匹配任何已知约定。
ARKit	1	Apple ARKit 52-blendshape 约定。大多数 VRoid 和 MetaHuman 导出的 rig 都使用它。
ReallusionCC3	2	Reallusion Character Creator 3 的基础面部 rig。
MetaHuman	3	Epic MetaHuman 原生面部 rig。
ReallusionCC4Extended	4	Reallusion Character Creator 4 Extended 面部配置文件——严格来说是 ReallusionCC3.
Custom	99	的超集。 CustomRigConventionMap 该 rig 不匹配任何内置约定；由一个

相关参考

具身化如何工作角色骨架设置角色具身化