> 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-unity-sdk/embodiment/gaze/quick-start.md).

# Gaze 快速开始

将 Gaze 模块添加到现有 Convai 角色，并确认它在 Play 模式下立即与玩家进行眼神接触。

添加 `ConvaiGazeController` 到现有的 Convai 角色上，并在 Play 模式下确认它会与玩家进行眼神交流。请在场景中已有可正常运行的 `ConvaiCharacter` 且想在调整任何设置前查看 Gaze 的运行效果时，使用此页面。

### 前提条件

* 一个 `ConvaiCharacter` 在场景中已连接并能正常响应的角色——如果尚未完成，请先完成 [验证设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/validate-your-setup.md) 。
* 具有可解析头部骨骼的骨架： **Humanoid** 骨架会自动解析；Generic 骨架或不带动画器的骨架则需添加 [角色骨架绑定](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md) 并至少指定头部骨骼后才能使用。

{% hint style="info" %}
Gaze 无需 `ConvaiGazeProfile` 资源也能运行。仅添加此组件，它就会使用 SDK 内置的参数运行；配置文件用于之后调整行为，而不是用于启用模块。
{% endhint %}

### 添加 Gaze 组件

{% stepper %}
{% step %}

#### 选择角色

在层级视图中，选择 `GameObject` 上带有 `ConvaiCharacter` 组件的对象。
{% endstep %}

{% step %}

#### 添加 Gaze 组件

在检查器中，选择 **添加组件**，然后选择 **Convai > Embodiment > Gaze**。这会添加 `ConvaiGazeController` 到角色上。

Convai 还会自动为模块添加所需的基础设施，包括 `EmbodimentContext`、 `StandardRigBinding`以及控制器所需的内部 `GazeAttentionRequests` 组件。你无需自行添加其中任何一项。
{% endstep %}

{% step %}

#### 检查就绪状态

该 `ConvaiGazeController` 检查器会报告该组件是否可以运行： **就绪** 表示 Gaze 已解析出头部骨骼，按下 Play 后即可运行。 **无法运行** 仅当骨架没有可供 Gaze 旋转的头部骨骼时才会出现，检查器会指出如何修复。
{% endstep %}
{% endstepper %}

### 验证设置

进入 Play 模式并与角色开始对话。Gaze 的默认眼神接触模式为 `Natural`，它会根据角色的对话状态调整：当角色处于 `Idle`时忽略玩家；处于 `Attending`, `Listening`和 `Speaking`时保持眼神接触；在 `Thinking`时短暂移开视线进行思考。对话过程中移动到角色身后，它会转过身来面对你。

{% hint style="success" %}
**预期结果：** 对话开始后不久，角色的眼睛和头部会转向你；你说话以及角色回应时，它会保持眼神接触；如果你在对话过程中移动到它身后，角色会转过身来面对你。
{% endhint %}

### 故障排查

如果角色的眼睛和头部没有移动，请打开 `ConvaiGazeController` 检查器，首先查看就绪状态—— **Not working** 会直接指出缺少的骨骼。如果状态显示为 **Ready** ，但在播放模式下仍没有任何动作，请参阅 [注视功能故障排查](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/troubleshooting.md) ，了解其他可能的故障原因。

### 后续步骤

{% content-ref url="/pages/adea0a04a9b4030ac04e68f9303f887133a23c5b" %}
[视线工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/how-gaze-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/3e45c80fb1153e604c743a1f3a0a835d39719b0e" %}
[配置眼神接触](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/configure-eye-contact.md)
{% endcontent-ref %}

{% content-ref url="/pages/beb7fd6775b7e9b4da287a76d337e2f0e2a2b17f" %}
[排查视线问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/troubleshooting.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-unity-sdk/embodiment/gaze/quick-start.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.
