场景组件参考

Convai Chatbot、Player、Object 和 Face Sync 组件的参考——它们的字段、运行时属性，以及它们在场景中如何连接。

本页是 Convai 插件提供的四个组件的参考。请在构建或调试场景时使用它。有关添加组件的逐步演示，请参见 添加你的第一个 Convai 角色.

Convai Unreal Engine 插件向 Unreal Engine 添加了四个组件。每个组件都有不同的职责——了解它们的作用可避免最常见的连接错误。

组件职责

组件	类	在“添加”菜单中搜索名称	附加到
Convai 聊天机器人	UConvaiChatbotComponent	BP Convai ChatBot 组件	NPC 角色蓝图
Convai Player	UConvaiPlayerComponent	BP Convai Player 组件	玩家 Pawn 蓝图
Convai Object	UConvaiObjectComponent	Convai Object	AI 应该了解的场景内任意 Actor
Convai 面部同步	UConvaiFaceSyncComponent	Convai 面部同步	NPC 角色蓝图

BP 与裸组件： 搜索 BP Convai ChatBot 组件 或 BP Convai Player 组件 会添加 Blueprint 封装版本，其中预先连接了按键说话输入和聊天 UI 小组件。搜索 Convai 聊天机器人 或 Convai Player 会添加裸 C++ 组件——这可以工作，但需要你自己连接按键说话、聊天小组件和音频捕获。

组件如何连接

该 UConvaiPlayerComponent 和 UConvaiChatbotComponent 通过由以下对象管理的会话进行连接 UConvaiSubsystem ——一个插件会自动注册的游戏实例子系统。在大多数 Blueprint 设置中，你无需直接引用该子系统。

组件详情

Convai 聊天机器人

UConvaiChatbotComponent 是非玩家角色的 AI 大脑。它持有 CharacterID ，用于将该组件链接到你在 Convai 控制面板中创建的角色。在运行时，它会连接到 Convai，从一个 UConvaiPlayerComponent，并将响应流式返回。

可编辑的 Details 面板字段：

字段	默认值	描述
CharacterID	（空）	必需。 来自 Convai 控制面板的唯一 ID，用于标识该组件对应的角色。
bAutoInitializeSession	true	当 true，组件会在 BeginPlay 时自动连接到 Convai。设置为 false 以调用 StartSession() ，手动执行。
InterruptVoiceFadeOutDuration	1.0	角色语音音频淡出的时长（秒），当 InterruptSpeech 被调用时。 0 会立即切断音频。请参见 配置角色音频.

运行时值（只读）： CharacterName 会在会话加载后从角色的控制面板配置中填充。它是 BlueprintReadOnly ——可在 Blueprint 中读取，但不可在 详细信息 面板中编辑。请在 Convai 控制面板中管理角色配置。

有用的运行时函数（可在 Blueprint 中调用）：

函数	Blueprint 显示名称	返回值	描述
GetIsTalking()	正在说话	bool	true ，当角色正在说话时。
IsInConversation()	—	bool	true 当存在活动会话（监听、处理或说话）时。

IsListening() 和 IsProcessing() 在 Blueprint 中公开，但目前返回 false 在插件源代码中。请使用 GetIsTalking() 和 IsInConversation() 进行可靠的状态检查，直到这些函数实现为止。

该组件触发的 Blueprint 事件：

事件	描述
OnActionReceivedEvent_V2	角色已确定要执行的动作。
OnEmotionStateChangedEvent	角色的情绪状态已更新。
OnCharacterDataLoadEvent_V2	来自控制面板的角色元数据已准备就绪。
OnNarrativeSectionReceivedEvent	一个叙事设计段落被触发。
OnInteractionIDReceivedEvent	一个新交互已分配 ID。
OnInterruptedEvent	角色的语音被新的玩家输入打断。
OnFailureEvent	发生了网络或身份验证错误。

该 CharacterID 字段是唯一必需字段。所有其他字段都有可用的默认值。

Convai Player

Convai Object

Convai 面部同步

Blueprint 包装器

插件在 Content/中提供了每个组件的 Blueprint 封装版本。请使用这些版本而不是裸 C++ 组件——它们开箱即包含按键说话输入绑定、聊天小组件集成和音频捕获。

资源	Content 路径	包含内容
BP_ConvaiChatbotComponent (BP Convai ChatBot 组件)	ConvaiConveniencePack/ConvaiBPComponent/	UConvaiChatbotComponent 预先连接了按键说话和 Chat_WB.
BP_ConvaiPlayerComponent (BP Convai Player 组件)	ConvaiConveniencePack/ConvaiBPComponent/	UConvaiPlayerComponent 预先连接了按键说话、 Chat_WB，以及 UISelection.
BP_ConvaiSamplePlayer	ConvaiConveniencePack/Sample/	示例玩家 pawn，带有 BP_ConvaiPlayerComponent 已附加。
BP_SampleGameMode	ConvaiConveniencePack/Sample/	将 BP_ConvaiSamplePlayer 设为默认 pawn 的游戏模式。
BP_Convai3DWidgetComponent / WBP_3DChatWidget	ConvaiConveniencePack/3DWidget/	游戏世界中的 3D 聊天 UI 小组件组件。
Chat_WB / MicSettings_WB	Widgets/	屏幕空间聊天覆盖层和麦克风设置面板。
ConvaiPlayerWithVoiceActivation	Core/	默认启用语音激活（VAD）的玩家 pawn。

ConvaiBasePlayer 和 ConvaiBaseCharacter 在 Content/Core/ 已弃用。请将你的类重新父类化为标准 Character 或 Pawn，并添加 BP_ConvaiPlayerComponent 或 BP_ConvaiChatbotComponent ，代替它。

下一步

验证你的设置配置对话输入