Convai Player 组件

玩家对话组件的参考——Convai Player Component 暴露的每个 Blueprint 可见属性、函数和事件。

UConvaiPlayerComponent （Blueprint 显示名称 Convai Player）被添加到玩家的 Actor 用于表示对话中的人类一方。它管理玩家与 Convai 的会话，捕获麦克风音频，将其流式传输到当前活动的聊天机器人会话，并提供视线注意力跟踪。

添加组件路径： Convai Player.

身份标识

这些属性用于向 Convai 标识玩家，并用于长期记忆关联。

属性	类型	访问	类别	描述
PlayerName	FString	任意位置可编辑, 已复制	Convai	聊天机器人用来称呼此玩家的显示名称。默认值： “User”。通过 Blueprint setter 设置时会调用 SetPlayerName，它还会调用 服务器可靠 RPC SetPlayerNameServer ，以便客户端可以更新自己的名称。
EndUserID	FString	任意位置可编辑，由 setter RPC 在服务器端更新	Convai	用于长期记忆的最终用户身份令牌。连接时发送给 Convai。Blueprint setter 会调用 SetEndUserIDServer 当组件被复制时，更新服务器副本。
EndUserMetadata	FString	任意位置可编辑，由 setter RPC 在服务器端更新	Convai	包含用于 LTM 的附加用户元数据的 JSON 字符串。Blueprint setter 会调用 SetEndUserMetadataServer 当组件被复制时，更新服务器副本。

SetPlayerName, SetEndUserID，和 SetEndUserMetadata 都各自有对应的 服务器可靠 RPC（SetPlayerNameServer, SetEndUserIDServer, SetEndUserMetadataServer）。在当前源代码中，只有 PlayerName 被注册到 DOREPLIFETIME; EndUserID 和 EndUserMetadata 会通过其 setter RPC 在服务器上更新，但不会作为属性复制回其他客户端。

会话

属性	类型	默认	类别	描述
bAutoInitializeSession	bool	true	Convai|Session	当 true，会在 StartSession 之后自动调用 Connected.

会话函数

函数	输入	返回值	类别	描述
StartSession	—	bool	Convai|Session	为此玩家打开 WebRTC 通道。返回 true 当会话成功初始化时。
StopSession	—	—	Convai|Session	关闭通道。再次调用 StartSession 会重新打开它。
IsPlayerConnected	—	bool	Convai|Session	BlueprintPure。返回 true 当会话处于 EC_ConnectionState::Connected 状态时。
SendText	ChatbotComponent (UConvaiConversationComponent*), Text (FString)	—	Convai|Session	发送 Text 到玩家的活动会话中，绕过麦克风管线。在当前源代码中， ChatbotComponent 引脚出现在签名中，但实现未使用它。

参见 会话生命周期 用于连接状态以及会话开始/停止行为。

麦克风捕获

玩家组件通过附加的 UConvaiAudioCaptureComponent 捕获麦克风音频并将其送入活动会话。

设备选择

函数	输入	返回 / 输出	类别	描述
GetDefaultCaptureDeviceInfo	—	bool 返回， OutInfo (FCaptureDeviceInfoBP) 输出	Convai|Microphone	当前源代码： 验证 AudioCaptureComponent，然后始终返回 false 而不填充 OutInfo。不要依赖此节点的 OutInfo 。请改用 GetAvailableCaptureDeviceDetails 或 GetActiveCaptureDevice 。另见 麦克风与音频捕获.
GetCaptureDeviceInfo	DeviceIndex (int)	bool 返回， OutInfo (FCaptureDeviceInfoBP) 输出	Convai|Microphone	返回给定 DeviceIndex.
GetAvailableCaptureDeviceDetails	—	TArray<FCaptureDeviceInfoBP> return	Convai|Microphone	返回所有可用捕获设备的详细信息。
GetAvailableCaptureDeviceNames	—	TArray<FString> return	Convai|Microphone	返回所有可用捕获设备的显示名称。
GetActiveCaptureDevice	—	OutInfo (FCaptureDeviceInfoBP) 输出	Convai|Microphone	填充 OutInfo ，使用当前选中的捕获设备。
SetCaptureDeviceByIndex	DeviceIndex (int)	bool return	Convai|Microphone	切换到给定索引的设备。返回 false 表示失败。
SetCaptureDeviceByName	DeviceName (FString)	bool return	Convai|Microphone	切换到枚举列表中名称匹配 DeviceName。返回 false 的最后一个设备。未找到匹配项时返回

FCaptureDeviceInfoBP 字段：

字段	类型	描述
DeviceName	FString	人类可读的设备名称。
DeviceIndex	int	设备列表中的索引。
LongDeviceId	FString	平台特定的设备标识符。
InputChannels	int	输入通道数。
PreferredSampleRate	int	设备首选采样率。
bSupportsHardwareAEC	bool	true 表示设备支持硬件回声消除时。

FCaptureDeviceInfoBP 也在中随音频捕获组件一并记录 麦克风与音频捕获.

音量

函数	输入	输出	类别	描述
SetMicrophoneVolumeMultiplier	InVolumeMultiplier (float)	Success (bool) 输出	Convai|Microphone	调整麦克风输入增益。 成功 反映的是是否有可用的捕获组件，而不是麦克风捕获当前是否正在流式传输或录制。
GetMicrophoneVolumeMultiplier	—	OutVolumeMultiplier (float) 输出， Success (bool) 输出	Convai|Microphone	读取当前麦克风音量乘数。 成功 反映捕获组件的可用性。

音频流式传输与录制

流式传输

这些函数控制是否将麦克风音频实时发送到活动会话。

函数	返回值	类别	描述
UnmuteStreamingAudio	bool	Convai|Session	开始将麦克风音频转发到会话。返回 true 表示成功。
MuteStreamingAudio	—	Convai|Session	停止转发麦克风音频。
GetIsStreaming （显示名称 正在流式传输)	bool	Convai|Microphone	BlueprintPure. true 当麦克风音频正在流式传输时。

录制

使用录制来捕获完整的话语并获得一个 USoundWave.

函数	返回值	类别	描述
StartRecording	—	Convai|Microphone	开始缓冲麦克风音频。调用 FinishRecording 以停止并检索音频。
FinishRecording	USoundWave*	Convai|Microphone	停止录制并将捕获的音频返回为一个 USoundWave。返回 null 当未录制到任何音频时。
GetIsRecording （显示名称 正在录制)	bool	Convai|Microphone	BlueprintPure. true 在录制进行中时。

静音与语音活动检测

属性	类型	默认	类别	描述
bMute	bool	false	Convai|AudioProcessing	当 true，会阻止直接的非音频处理流式传输路径。使用活动的 IConvaiAudioProcessingInterface时，经过处理的音频仍可由当前实现转发。

函数	输入	返回值	类别	描述
UpdateVadBP	EnableVAD (bool)	bool	Convai|AudioProcessing	启用或禁用语音活动检测。返回 false 当当前音频处理组件不支持 VAD 时。

视线注意力

视线注意力允许玩家组件根据玩家的注视方向，自动将场景中的对象提升为聊天机器人的“注意对象”。使用 bEnableGazeAttention启用该系统。有关完整的跨组件 API、默认值、事件以及特定版本的高亮行为，请参见 视线注意力参考.

核心设置

属性	类型	默认	类别	描述
bEnableGazeAttention	bool	false	Convai|Gaze Attention	主开关。以下所有视线注意力属性在此项为 false.
GazeShouldRespond	EC_RunLLMOption	从不	Convai|Gaze Attention	控制当对象被提升为注意对象时，聊天机器人是否回复： 从不 （静默更新）， Auto （LLM 决定），或 始终 （强制回复）。
GazeAttentionText	FString	""	Convai|Gaze Attention	与注意力提升一起发送的叙事事件文本。当前设置为 GazeShouldRespond 是 从不.
GazeAttentionDelay	float	1.0	Convai|Gaze Attention	对象被提升为“注意对象”之前持续注视的秒数。
GazeAttentionLossDelay	float	5.0	Convai|Gaze Attention	当前注意槽位被释放前的移开视线持续时间（秒）。
GazeMaxDistance	float	5000.0	Convai|Gaze Attention （高级）	从摄像机出发的最大射线检测距离，世界单位（cm）。
GazeAngleTolerance	float	5.0	Convai|Gaze Attention	当严格的线性射线检测未命中有效注视目标且未被非 Convai 几何体阻挡时使用的点积回退锥半角（度）。 0 会禁用回退。
GazeTraceChannel	ECollisionChannel	ECC_Visibility	Convai|Gaze Attention （高级）	视线线性射线检测使用的碰撞通道。

GazeShouldRespond 接受 EC_RunLLMOption 值（Auto, 始终, 从不）。有关值说明，请参见 数据类型与枚举.

高亮设置

这些设置控制绘制在被注视对象上的轮廓叠加层。

属性	类型	默认	类别	描述
GazeHighlightActorClass	TSubclassOf<AConvaiGazeHighlightActor>	插件默认值	Convai|Gaze Attention|Highlight	用于显示高亮效果的生成演员类。可子类化 AConvaiGazeHighlightActor 以实现自定义视觉效果。
GazeHighlightColor	FLinearColor	(1.0, 0.9, 0.2, 1.0)	Convai|Gaze Attention|Highlight	应用于轮廓或线框的色调。
GazeOverlayMaterial	TSoftObjectPtr<UMaterialInterface>	未设置	Convai|Gaze Attention|Highlight	通过以下方式应用的叠加材质 UMeshComponent::SetOverlayMaterial。留空则使用插件内置的菲涅尔边缘材质（/ConvAI/Highlights/M_ConvaiGazeOverlay）。该材质必须提供一个 EmissiveColor 向量参数。
GazeHighlightEmissiveIntensity	float	2.5	Convai|Gaze Attention|Highlight （高级）	转发到高亮演员的 EmissiveIntensity 标量参数。插件叠加材质会在内部将 EmissiveColor 乘以该值。

光标设置

属性	类型	默认	类别	描述
bShowGazeCursor	bool	true	Convai|Gaze Attention|Cursor	在视线跟踪激活时，在屏幕中心显示一个小准星。
bAlwaysShowGazeCursor	bool	false	Convai|Gaze Attention|Cursor	当 true时，即使注视下没有 Convai 对象，光标也会保持其 Active 颜色。
GazeCursorWidgetClass	TSubclassOf<UConvaiGazeCursorWidget>	插件默认值	Convai|Gaze Attention|Cursor	用于绘制光标的小部件类。
GazeCursorActiveColor	FLinearColor	白色	Convai|Gaze Attention|Cursor	当视线落在一个 UConvaiObjectComponent.
GazeCursorIdleColor	FLinearColor	(1.0, 1.0, 1.0, 0.0)	Convai|Gaze Attention|Cursor （高级）	当视线落空时的光标颜色。默认 alpha 0.0 会使光标在空闲时完全透明。
GazeCursorDotSize	float	6.0	Convai|Gaze Attention|Cursor （高级）	Slate 单位中的光标方块边长。
GazeCursorFadeInTime	float	0.1	Convai|Gaze Attention|Cursor （高级）	当视线首次命中 Convai 对象时，光标从空闲淡入到活动所需的秒数。
GazeCursorFadeOutTime	float	0.25	Convai|Gaze Attention|Cursor （高级）	当视线离开 Convai 对象时，光标从活动淡出到空闲所需的秒数。

事件（可由 Blueprint 绑定的委托）

在玩家 Blueprint 中使用 分配 节点绑定这些委托，位于 Convai Player 组件引用上。

继承自 UConvaiConversationComponent

事件	类别	在以下情况触发
OnTranscriptionReceivedDelegate	Convai|Transcription	该玩家的话语收到语音转文字更新时。参数： Speaker, Listener, Transcription (FString), IsTranscriptionReady (bool), IsFinal (bool).
OnAttendeeConnectionStateChangedEvent	Convai|Connection	某个参与者的连接状态发生变化。参数： ConvaiConversationComponent, AttendeeID (FString), ConnectionState (EC_ConnectionState).

视线事件

所有四个视线委托都使用相同的签名： PlayerComponent (UConvaiPlayerComponent*) 和 ObjectComponent (UConvaiObjectComponent*).

大多数视线事件在 bEnableGazeAttention 是 true; OnAttentionLost 期间触发；当视线注意力被禁用时，在清理过程中也可能触发。

事件	类别	在以下情况触发
OnGazeBegin	Convai|Gaze Attention|Events	玩家的视线首次进入某个 UConvaiObjectComponent的边界。
OnGazeEnd	Convai|Gaze Attention|Events	玩家的视线离开一个 UConvaiObjectComponent，无论它是否已被提升为注意对象。
OnAttentionGained	Convai|Gaze Attention|Events	已达到持续注视停留阈值（GazeAttentionDelay），并尝试进行视线提升。即使所有聊天机器人都拒绝更新，也会触发。
OnAttentionLost	Convai|Gaze Attention|Events	注意槽位被释放：玩家的目光离开时间超过了 GazeAttentionLossDelay，另一个对象占用了该槽位，或者注意对象被销毁。

参见 事件系统 用于绑定模式和完整参数详情。有关麦克风设置和视线任务流程，请参见 配置麦克风 和 视线注意力参考.

相关参考

Convai Chatbot 组件麦克风和音频采集会话生命周期事件系统