> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-player-component.md).

# Convai 玩家组件

`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` 当组件被复制时，更新服务器副本。                                        |

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

### 会话

| 属性                       | 类型     | 默认     | 类别                | 描述                                             |
| ------------------------ | ------ | ------ | ----------------- | ---------------------------------------------- |
| `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` 引脚出现在签名中，但实现未使用它。 |

参见 [会话生命周期](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md) 用于连接状态以及会话开始/停止行为。

### 麦克风捕获

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

#### 设备选择

| 函数                                 | 输入                     | 返回 / 输出                                        | 类别                   | 描述                                                                                                                                                                                                                                                                                           |
| ---------------------------------- | ---------------------- | ---------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetDefaultCaptureDeviceInfo`      | —                      | `bool` 返回， `OutInfo (FCaptureDeviceInfoBP)` 输出 | `Convai\|Microphone` | **当前源代码：** 验证 `AudioCaptureComponent`，然后始终返回 `false` 而不填充 `OutInfo`。不要依赖此节点的 `OutInfo` 。请改用 `GetAvailableCaptureDeviceDetails` 或 `GetActiveCaptureDevice` 。另见 [麦克风与音频捕获](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/microphone-and-audio-capture.md). |
| `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` 也在中随音频捕获组件一并记录 [麦克风与音频捕获](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/microphone-and-audio-capture.md).

#### 音量

| 函数                              | 输入                           | 输出                                                    | 类别                   | 描述                                                    |
| ------------------------------- | ---------------------------- | ----------------------------------------------------- | -------------------- | ----------------------------------------------------- |
| `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、默认值、事件以及特定版本的高亮行为，请参见 [视线注意力参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-reference.md).

#### 核心设置

| 属性                       | 类型                  | 默认               | 类别                            | 描述                                                                    |
| ------------------------ | ------------------- | ---------------- | ----------------------------- | --------------------------------------------------------------------- |
| `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`, `始终`, `从不`）。有关值说明，请参见 [数据类型与枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

#### 高亮设置

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

| 属性                               | 类型                                       | 默认                     | 类别                                       | 描述                                                                                                                                             |
| -------------------------------- | ---------------------------------------- | ---------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `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`，另一个对象占用了该槽位，或者注意对象被销毁。 |

参见 [事件系统](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/event-system.md) 用于绑定模式和完整参数详情。有关麦克风设置和视线任务流程，请参见 [配置麦克风](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-the-microphone.md) 和 [视线注意力参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-reference.md).

### 相关参考

{% content-ref url="/pages/4a6e5ee0afdb709983f0b5685e8cf00febcf5282" %}
[Convai 聊天机器人组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-chatbot-component.md)
{% endcontent-ref %}

{% content-ref url="/pages/66c756b3aff92ca8b5e88b114dba034ef0b5618c" %}
[麦克风和音频捕获](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/microphone-and-audio-capture.md)
{% endcontent-ref %}

{% content-ref url="/pages/a8878427b216a80d6b385f1a342c440aa9b398c9" %}
[会话生命周期](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md)
{% endcontent-ref %}

{% content-ref url="/pages/ddcceab71734a05a1e99c8599b42f364e146005e" %}
[事件系统](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/event-system.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-player-component.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.