> 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/features/character-actions.md).

# 角色动作

角色动作让 Convai 角色能够对玩家所说内容做出场景内行为响应——走向目标、进行眼神接触、播放手势，或运行你自己的游戏代码。Convai 会识别要执行的动作以及要针对的目标；Actions Editor 是你添加和配置这 21 个内置执行器、或接入你自己的执行器的地方。本节涵盖从你的第一个动作到完整脚本 API 的所有内容。

有几个内置执行器通过 Gaze 和 Body Animation 具身模块运行，因此角色在这些动作生效前需要安装匹配的模块——见 [实体化](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment.md).

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>角色动作的工作原理</strong><br>了解流程、关键概念、必需组件和内置执行器。</td><td><a href="/pages/53aa8db086c9806f093f80741862dfe3316e77d8">/pages/53aa8db086c9806f093f80741862dfe3316e77d8</a></td></tr><tr><td><strong>角色动作快速入门</strong><br>从 Actions Editor 的入门目录中为你的 NPC 添加一个现成动作——无需编写脚本。</td><td><a href="/pages/7f0d213ddc809cfd39ab2bc41492ddf8e54b6c19">/pages/7f0d213ddc809cfd39ab2bc41492ddf8e54b6c19</a></td></tr><tr><td><strong>Actions Editor</strong><br>Actions Editor 窗口参考：Add Action 目录，以及一键配置执行器。</td><td><a href="/pages/b1d09b6e9430d66a69feaa877bc4844f6ed840d0">/pages/b1d09b6e9430d66a69feaa877bc4844f6ed840d0</a></td></tr><tr><td><strong>配置角色动作</strong><br>完整参考： <code>ConvaiActionConfigSource</code> ——动作定义、目标以及连接时覆盖项。</td><td><a href="/pages/111bca064ba7041a987662d038af4d71d58a32cd">/pages/111bca064ba7041a987662d038af4d71d58a32cd</a></td></tr><tr><td><strong>在运行时更新角色动作</strong><br>Apply <code>ConvaiActionConfigPatch</code> 在会话处于活动状态时，对动作、对象、角色和注意力的更新，并由 Convai 的确认予以确认。</td><td><a href="/pages/4001c6ae3c6d4603942748007a37a67812bb7e9a">/pages/4001c6ae3c6d4603942748007a37a67812bb7e9a</a></td></tr><tr><td><strong>动作执行器</strong><br>包含所有 21 个执行器组件的参考及 Inspector 字段表。</td><td><a href="/pages/f592d9dc3ad261e175159690b86cdd4b50bb4d81">/pages/f592d9dc3ad261e175159690b86cdd4b50bb4d81</a></td></tr><tr><td><strong>分发器和批次策略</strong><br>配置 <code>ConvaiActionDispatcher</code> 如何处理并发批次和步骤失败。</td><td><a href="/pages/6e3c85bad169c9c2c755b38be39008ef3ce023cf">/pages/6e3c85bad169c9c2c755b38be39008ef3ce023cf</a></td></tr><tr><td><strong>编写自定义动作执行器</strong><br>实现 <code>IConvaiActionExecutor</code> 为任何动作创建项目专属行为。</td><td><a href="/pages/c5598abd0ddd72fa75a0989ad602a5b4d12e16d7">/pages/c5598abd0ddd72fa75a0989ad602a5b4d12e16d7</a></td></tr><tr><td><strong>动作目标解析的工作方式</strong><br>命令中的目标词如何与场景中的真实对象匹配，以及注意力如何缩小匹配范围。</td><td><a href="/pages/5b02ee57da9de48585f7ea92aa9e94714547d80a">/pages/5b02ee57da9de48585f7ea92aa9e94714547d80a</a></td></tr><tr><td><strong>角色动作脚本参考</strong><br>涵盖所有动作系统类型、事件、枚举和组件的完整公共 API。</td><td><a href="/pages/0341126fa4c492311dab4fb6aca6d0c64191016b">/pages/0341126fa4c492311dab4fb6aca6d0c64191016b</a></td></tr><tr><td><strong>角色动作示例</strong><br>五个逐步推进的场景，从无需代码的 Inspector 设置到脚本化批量注入和与语音同步的时序。</td><td><a href="/pages/0e9ccbf7f8fa10ad65f6395315d82ba64412791c">/pages/0e9ccbf7f8fa10ad65f6395315d82ba64412791c</a></td></tr><tr><td><strong>将动作迁移到 v4.5.0</strong><br>为 4.5.0 之前的项目更新重组后的执行器库，包括已重命名的 <code>ConvaiUnityEventActionExecutor</code> GUID 更改。</td><td><a href="/pages/7905d34249d33be76079e6f5bb2876a37dea1fe2">/pages/7905d34249d33be76079e6f5bb2876a37dea1fe2</a></td></tr><tr><td><strong>排查角色动作问题</strong><br>使用 Action Troubleshooter 和症状/原因/修复参考来诊断动作管道问题。</td><td><a href="/pages/1398e3302b345ef93934a0e6c93b4d8e576ab00e">/pages/1398e3302b345ef93934a0e6c93b4d8e576ab00e</a></td></tr></tbody></table>


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.