> 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 玩家组件

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

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

添加组件路径： **Convai 播放器**.

### 身份

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

| 属性                | 类型        | 访问                          | 类别       | 说明                                                                                                                        |
| ----------------- | --------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `PlayerName`      | `FString` | `任意编辑`, `已复制`               | `Convai` | 聊天机器人用于称呼该玩家的显示名称。默认： `“用户”`。通过蓝图 setter 设置时会调用 `SetPlayerName`，它还会调用 `服务器可靠` RPC `SetPlayerNameServer` ，这样客户端就可以更新自己的名字。 |
| `EndUserID`       | `FString` | `任意编辑`，由 setter RPC 在服务器上更新 | `Convai` | 用于长期记忆的最终用户身份令牌。连接时发送给 Convai。蓝图 setter 会调用 `SetEndUserIDServer` 当组件被复制时，会更新服务器副本。                                        |
| `EndUserMetadata` | `FString` | `任意编辑`，由 setter RPC 在服务器上更新 | `Convai` | 用于 LTM 的附加用户元数据 JSON 字符串。蓝图 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` 在 Convai 连接状态达到以下状态后自动： `已连接`. |

#### 会话函数

| 函数                  | 输入                                                                   | 返回     | 类别                | 说明                                                                      |
| ------------------- | -------------------------------------------------------------------- | ------ | ----------------- | ----------------------------------------------------------------------- |
| `StartSession`      | —                                                                    | `bool` | `Convai\|Session` | 为该玩家打开 WebRTC 通道。返回 `true` 当会话成功初始化时。                                   |
| `StopSession`       | —                                                                    | —      | `Convai\|Session` | 关闭通道。再次调用 `StartSession` 会重新打开它。                                        |
| `IsPlayerConnected` | —                                                                    | `bool` | `Convai\|Session` | `蓝图纯函数`。返回 `true` 当会话处于 `EC_ConnectionState::Connected` 状态时。            |
| `SendText`          | `ChatbotComponent (UConvaiConversationComponent*)`, `Text (FString)` | —      | `Convai\|Session` | 发送 `文本` 到玩家的活动会话中，绕过麦克风管线。在当前源代码中， `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>` 返回              | `Convai\|Microphone` | 返回所有可用采集设备的详细信息。                                                                                                                                                                                                                                                                                |
| `GetAvailableCaptureDeviceNames`   | —                      | `TArray<FString>` 返回                           | `Convai\|Microphone` | 返回所有可用采集设备的显示名称。                                                                                                                                                                                                                                                                                |
| `GetActiveCaptureDevice`           | —                      | `OutInfo (FCaptureDeviceInfoBP)` 输出            | `Convai\|Microphone` | 填充 `OutInfo` 包含当前选中的采集设备。                                                                                                                                                                                                                                                                       |
| `SetCaptureDeviceByIndex`          | `DeviceIndex (int)`    | `bool` 返回                                      | `Convai\|Microphone` | 切换到给定索引的设备。成功返回 `false` 失败时返回。                                                                                                                                                                                                                                                                  |
| `SetCaptureDeviceByName`           | `DeviceName (FString)` | `bool` 返回                                      | `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` | `蓝图纯函数`. `true` 当麦克风音频正在流式传输时。 |

#### 录制

使用录制来捕获完整的语音片段并获取一个 `USoundWave`.

| 函数                               | 返回            | 类别                   | 说明                                                 |
| -------------------------------- | ------------- | -------------------- | -------------------------------------------------- |
| `StartRecording`                 | —             | `Convai\|Microphone` | 开始缓冲麦克风音频。调用 `FinishRecording` 以停止并获取音频。           |
| `FinishRecording`                | `USoundWave*` | `Convai\|Microphone` | 停止录制，并将捕获的音频作为 `USoundWave`。返回 `null` 当未录制任何音频时返回。 |
| `GetIsRecording` （显示名称 **正在录制**) | `bool`        | `Convai\|Microphone` | `蓝图纯函数`. `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`   | `Never`          | `Convai\|Gaze Attention`      | 控制当对象被提升为关注对象时聊天机器人是否回复： `Never` （静默更新）， `自动` （由 LLM 决定），或 `Always` （强制回复）。 |
| `GazeAttentionText`      | `FString`           | `""`             | `Convai\|Gaze Attention`      | 随关注提升一并发送的叙事事件文本。当 `GazeShouldRespond` 是 `Never`.                           |
| `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` 值（`自动`, `Always`, `Never`）。有关值说明，请参见 [数据类型和枚举](/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`      | 用于显示高亮而生成的 Actor 类。请继承 `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` （高级） | 转发给高亮 Actor 的 `EmissiveIntensity` 标量参数。插件叠加材质会将 `EmissiveColor` 在内部乘以该值。                                                                           |

#### 光标设置

| 属性                      | 类型                                     | 默认值                    | 类别                                    | 说明                                            |
| ----------------------- | -------------------------------------- | ---------------------- | ------------------------------------- | --------------------------------------------- |
| `bShowGazeCursor`       | `bool`                                 | `true`                 | `Convai\|Gaze Attention\|Cursor`      | 在凝视追踪激活时，在屏幕中央显示一个小准星。                        |
| `bAlwaysShowGazeCursor` | `bool`                                 | `false`                | `Convai\|Gaze Attention\|Cursor`      | 当 `true`，即使凝视下没有 Convai 对象，光标也会保持其激活颜色。       |
| `GazeCursorWidgetClass` | `TSubclassOf<UConvaiGazeCursorWidget>` | 插件默认值                  | `Convai\|Gaze Attention\|Cursor`      | 用于绘制光标的小部件类。                                  |
| `凝视光标激活颜色`              | `FLinearColor`                         | 白色                     | `Convai\|Gaze Attention\|Cursor`      | 当凝视落在 `UConvaiObjectComponent`.               |
| `凝视光标空闲颜色`              | `FLinearColor`                         | `(1.0, 1.0, 1.0, 0.0)` | `Convai\|Gaze Attention\|Cursor` （高级） | 当凝视未指向任何对象时的光标颜色。默认 alpha `0.0` 会使光标在空闲时完全透明。 |
| `凝视光标点大小`               | `float`                                | `6.0`                  | `Convai\|Gaze Attention\|Cursor` （高级） | 光标方形边长，单位为 Slate 单位。                          |
| `凝视光标淡入时间`              | `float`                                | `0.1`                  | `Convai\|Gaze Attention\|Cursor` （高级） | 当凝视首次命中 Convai 对象时，光标从空闲淡入激活所需的秒数。            |
| `凝视光标淡出时间`              | `float`                                | `0.25`                 | `Convai\|Gaze Attention\|Cursor` （高级） | 当凝视离开 Convai 对象时，光标从激活淡出到空闲所需的秒数。             |

### 事件（可通过蓝图绑定的委托）

在玩家蓝图中使用以下项绑定这些委托： **分配** 节点上的 `Convai 播放器` 组件引用。

#### 继承自 `UConvaiConversationComponent`

| 事件                                      | 类别                      | 在以下情况触发：                                                                                                           |
| --------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `OnTranscriptionReceivedDelegate`       | `Convai\|Transcription` | 当该玩家的发言收到语音转文本更新时触发。参数： `说话者`, `听者`, `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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.