> 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/body-animation/config-reference.md).

# 身体动画配置参考

Convai Body Animation 配置资源中每个设置组和字段的参考，包括每项的默认值和取值范围。

`ConvaiBodyAnimationConfig` (`Convai/具身/身体动画配置`) 是 Convai 身体动画的运行时调优资源：过渡时序、层行为、运动同步、功能开关和诊断。内容位于一个单独的 `ConvaiBodyAnimationSet`;此资源只塑造行为，因此一个配置可以在多个角色之间共享。其 91 个序列化字段分组为 11 个命名部分，每个 `##` 对应下方的每个部分，与配置资源自身的 Inspector 以及 Body Animation Editor 窗口的 Feel 模式一致。

### 个性

这个角色的举止风格。一个动画库，多种不同的人。

| 字段      | 类型      | 默认  | 范围      | 说明                                                                 |
| ------- | ------- | --- | ------- | ------------------------------------------------------------------ |
| `手势生动度` | `float` | `1` | `0`–`2` | 放大说话手势的表现力：说话叠加层权重上限、循环时切换变体的概率，以及拍点手势频率（通过不应期窗口反向影响）。 `1` 复现默认行为。 |
| `沉稳度`   | `float` | `1` | `0`–`2` | 拉长待机变体间隔，并略微延长说话淡入。数值越高，角色显得越沉着、越深思熟虑。                             |

### 说话

角色说话时如何做手势。

| 字段           | 类型      | 默认     | 范围        | 说明                                                                                                                                                                                             |
| ------------ | ------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `说话淡入秒数`     | `float` | `0.5`  | `>= 0.01` | 角色开始说话时，说话层淡入。                                                                                                                                                                                 |
| `说话淡出秒数`     | `float` | `0.9`  | `>= 0.01` | 角色停止说话时，说话层淡出。                                                                                                                                                                                 |
| `说话释放延迟秒数`   | `float` | `0.16` | `>= 0`    | 语音停止后，在说话层淡出前短暂保持，让当前手势先稳定下来再过渡到待机。                                                                                                                                                            |
| `说话释放播放速度`   | `float` | `0.2`  | `0`–`1`   | 语音释放窗口期间的播放速度。放慢片段可防止预制的手臂动作在说话结束后继续上抬。                                                                                                                                                        |
| `说话释放提前秒数`   | `float` | `0.6`  | `>= 0`    | 角色在说话结束前多久开始放下双手。若角色有 Lip Sync 语音播放读取，则从中读取；见 [说话层如何释放](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/how-body-animation-works.md#how-the-talk-layer-releases). |
| `使用语音能量`     | `布尔值`   | `是`    | —         | 根据实时语音能量缩放说话层权重，使轻声说话时手势更少。                                                                                                                                                                    |
| `低语音能量时说话权重` | `float` | `0.2`  | `0`–`1`   | 在零语音能量时，说话层权重，适用于 `使用语音能量` 开启时显示。                                                                                                                                                              |
| `说话叠加层权重`    | `float` | `0.45` | `0`–`1`   | 说话叠加层可达到的最大权重。数值越低，说话手势下保留的待机姿势越多。                                                                                                                                                             |
| `循环时切换说话变体`  | `布尔值`   | `是`    | —         | 当前说话变体循环时切换到另一种变体，使长段讲话更有变化。                                                                                                                                                                   |
| `说话变体交叉淡化秒数` | `float` | `0.5`  | `>= 0.01` | 长段说话期间在不同说话变体之间交叉淡化。                                                                                                                                                                           |
| `说话尾段最长秒数`   | `float` | `0.7`  | `>= 0.05` | 说话结束时，预制的 Outro Clip 可能引入的附加延迟上限，这样较长的收尾片段也不会拖延回到待机状态。                                                                                                                                         |

### 走动时说话

说话手势是在静止状态下制作的。这里决定角色在做手势和行走同时发生时会怎样。

| 字段          | 类型        | 默认     | 范围                 | 说明                                                                                                   |
| ----------- | --------- | ------ | ------------------ | ---------------------------------------------------------------------------------------------------- |
| `移动中说话`     | `移动中说话模式` | `自动`   | `自动`, `弱化覆盖`, `抑制` | `自动` 对具有 Additive Clip 的条目，在步态之上播放增量手势；对没有 Additive Clip 的条目，则弱化覆盖； `弱化覆盖` 始终使用降权覆盖； `抑制` 移动时完全淡出说话。 |
| `移动中说话权重`   | `float`   | `0.7`  | `0`–`1`            | 使用 Additive Clip 时，移动中的增量走路+说话叠加层（手臂和手）的权重。                                                          |
| `移动中说话覆盖权重` | `float`   | `0.45` | `0`–`1`            | 没有 Additive Clip 时，移动中覆盖说话权重的上限。                                                                     |
| `移动中说话混合秒数` | `float`   | `0.35` | `>= 0.05`          | 在说话过程中开始或停止移动时，在静止和移动说话叠加层之间交叉淡化。                                                                    |

### 倾听与思考

玩家说话时以及回复前停顿期间保持的姿势。动画集中需要 Listen/Think 片段。

| 字段         | 类型      | 默认    | 范围        | 说明                                               |
| ---------- | ------- | ----- | --------- | ------------------------------------------------ |
| `倾听淡入秒数`   | `float` | `0.8` | `>= 0.01` | 进入 Listen 姿势时，说话层淡入。                             |
| `思考进入延迟秒数` | `float` | `0.4` | `>= 0`    | 秒 `思考中` 必须持续这么久，Think 姿势才会生效。不到一秒的回复不会让思考姿势瞬闪进出。 |

### 反应中

被打断、强调语音节奏，以及对所说内容做指向性手势。手势功能需要动画集中带标签的片段。

| 字段            | 类型      | 默认     | 范围         | 说明                                                                             |
| ------------- | ------- | ------ | ---------- | ------------------------------------------------------------------------------ |
| `被打断冻结秒数`     | `float` | `0.25` | `>= 0`     | 当 `DialogueState` 变为 `被打断` 在说话播放时，当前姿势会冻结（而非淡出）多久，然后才开始更快的被打断释放。               |
| `被打断释放缩放`     | `float` | `0.6`  | `0.05`–`1` | 的乘数 `说话淡出秒数` 用于跟在打断冻结之后的释放。                                                    |
| `启用拍点手势`      | `布尔值`   | `否`    | —          | 在检测到语音能量起点时触发短促的增量拍点手势，叠加在说话层之上。默认关闭——它播放带标签的预制片段 `拍点`/`强调` 且没有程序化替代方案。        |
| `拍点不应期秒数`     | `float` | `1.2`  | `>= 0.05`  | 两次拍点手势之间的最小秒数。                                                                 |
| `拍点权重缩放`      | `float` | `1`    | `0`–`1.5`  | 拍点手势基于起始强度计算出的权重的乘数。                                                           |
| `拍点层权重`       | `float` | `1`    | `0`–`1`    | 语音重音叠加在说话手势之上的强度。                                                              |
| `启用指代性手势`     | `布尔值`   | `是`    | —          | 对角色所说内容做手势——第二人称、第一人称、某个命名场景对象，或序数/数字词。带有该提示标签的预制片段会直接播放；没有此类片段的集合则把提示交给同伴表演者。 |
| `指代性手势不应期秒数`  | `float` | `6`    | `1`–`30`   | 任意两次指代性手势之间的最小秒数。                                                              |
| `指代性手势类别冷却秒数` | `float` | `10`   | `1`–`60`   | 同一类指代性手势再次触发前的最小秒数。                                                            |
| `指代性手势权重`     | `float` | `1`    | `0`–`1.5`  | 指代性手势权重的乘数，位于距离表现力乘数之前。                                                        |

### Presence

当没有其他事情发生时，角色在玩家周围的行为方式。

| 字段             | 类型      | 默认        | 范围                               | 说明                                                                                       |
| -------------- | ------- | --------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
| `距离表现力`        | `布尔值`   | `是`       | —                                | 根据对话距离缩放说话手势的表现力：距离越近越含蓄，距离越远越夸张。                                                        |
| `近距离阈值`        | `float` | `1.5` (米) | `>= 0.1`                         | 小于或等于该距离时 `近距离缩放` 完全生效。                                                                  |
| `近距离缩放`        | `float` | `0.85`    | `0.8`–`1.15`                     | 表现力乘数，小于或等于 `近距离阈值`.                                                                     |
| `远距离阈值`        | `float` | `6` (米)   | `>= ProximityNearDistance + 0.1` | 大于或等于该距离时 `远距离缩放` 完全生效。                                                                  |
| `远距离缩放`        | `float` | `1.15`    | `0.8`–`1.15`                     | 表现力乘数，大于或等于 `远距离阈值`.                                                                     |
| `距离平滑秒数`       | `float` | `0.5`     | `>= 0.05`                        | 距离乘数平滑过渡的秒数，这样走近角色时，手势大小不会明显“抽动”放大。                                                      |
| `启用环境活动`       | `布尔值`   | `否`       | —                                | 执行一个 `环境`-标签动作，当一段时间没人接触角色时按随机节奏执行。默认关闭——它播放完整的预制表演，没有程序化替代。                             |
| `环境活动开始延迟秒数`   | `float` | `12`      | `3`–`120`                        | 秒 `空闲` 必须持续这么久，才允许触发第一次环境活动。                                                             |
| `环境活动间隔秒数`     | `float` | `20`      | `5`–`300`                        | 激活后环境活动之间的平均秒数（±40% 抖动）。                                                                 |
| `环境抑制距离`       | `float` | `4` (米)   | `1`–`20`                         | 当对话伙伴距离这么近或更近时，不会启动新的环境活动。                                                               |
| `启用社交间距`       | `布尔值`   | `否`       | —                                | 当对话伙伴持续停留在角色的个人空间气泡内时，进行一次简短的 NavMesh 重定位，而不是像雕像一样一动不动。                                  |
| `舒适半径`         | `float` | `0.7` (米) | `0.3`–`2`                        | 个人空间半径。持续的对话距离低于此值会触发重定位。                                                                |
| `舒适保持秒数`       | `float` | `0.6`     | `0.1`–`3`                        | 对话者必须持续处于其中的秒数 `舒适半径` 之后才会触发重定位。                                                         |
| `每分钟最大重定位次数`   | `整数`    | `3`       | `1`–`10`                         | 每滚动一分钟内社交间距重定位的硬上限。                                                                      |
| `启用指向瞥视`       | `布尔值`   | `是`       | —                                | 当角色指向某物时，在视线回到玩家之前也短暂瞥一眼该物体。需要一个 `IGazeGlanceHandler` 位于角色上（如果存在，Convai Gaze 模块会自动注册一个）。 |
| `指向瞥视秒数`       | `float` | `0.9`     | `0.2`–`3`                        | 指向瞥视保持多久后，视线返回玩家。                                                                        |
| `指向淡出秒数`       | `float` | `0.3`     | `>= 0.01`                        | 指向层淡入/淡出。                                                                                |
| `指向重新瞄准交叉淡化秒数` | `float` | `0.25`    | `>= 0.05`                        | 当实时指向手势重新瞄准新方向或在释放过程中重新指定目标时进行交叉淡化。                                                      |
| `指向层权重`        | `float` | `1`       | `0`–`1`                          | 指向手势在多大程度上替换其下方的手臂姿势。                                                                    |

### 走路与跑步

移动速度、角色原地转身的时机，以及允许播放哪些到达表演。

| 字段            | 类型      | 默认          | 范围                                    | 说明                                                      |
| ------------- | ------- | ----------- | ------------------------------------- | ------------------------------------------------------- |
| `步行速度`        | `float` | `1.2` (米/秒) | `>= 0.1`                              | 用于步行的代理速度指令；在 Clip Motion Analyzer 填充元数据之前，也是默认的预制步行速度。 |
| `慢跑速度`        | `float` | `2.6` (米/秒) | `>= 0.1`, `>= WalkSpeed`              | 用于慢跑的代理速度指令。                                            |
| `速度阻尼秒数`      | `float` | `0.12`      | `>= 0.01`                             | 驱动移动混合的代理速度读数的平滑时间。                                     |
| `原地转身最小角度`    | `float` | `60` （度）    | `>= 1`                                | 触发原地转身而不是直接移动的偏航误差。                                     |
| `180 度转身最小角度` | `float` | `135` （度）   | `>= 90`, `>= TurnInPlaceMinAngle + 5` | 偏航误差高于该值时，使用 180° 转身/起步变体。                              |
| `速率扭曲下限`      | `float` | `0.85`      | `0.5`–`1`                             | 播放速率扭曲的下限夹值（代理速度 ÷ 预制片段速度）。                             |
| `速率扭曲上限`      | `float` | `1.2`       | `1`–`1.5`, `>= RateWarpMin`           | 播放速率扭曲的上限夹值。                                            |
| `动作交接归一化时间`   | `float` | `0.85`      | `0.5`–`0.98`                          | 起步/转身/变速一次性片段交叉淡入其后续状态的归一化片段时间。                         |
| `低速停止比例`      | `float` | `0.6`       | `0.1`–`1`                             | 低于该步行速度比例时选择低速停止片段。                                     |
| `定脚停止最小行进距离`  | `float` | `1.2` (米)   | `>= 0`                                | 在可播放定脚停止片段之前，一条腿必须在巡航速度下覆盖的距离；更短的重定位则通过代理刹车和普通待机混合来收尾。  |
| `启用原地转身`      | `布尔值`   | `是`         | —                                     | 当角色在出发前必须面向新方向时，播放预制的转身片段。集合中需要转身片段。                    |
| `启用方向性起步`     | `布尔值`   | `是`         | —                                     | 使用为行进方向制作的片段开始行走。集合中需要起步片段。                             |
| `启用定脚停止`      | `布尔值`   | `是`         | —                                     | 用带有脚落地的预制停止动作完成移动。集合中需要停止片段。                            |
| `行走时也使用定脚停止`  | `布尔值`   | `否`         | —                                     | 在以步行速度到达时也播放定脚停止片段。默认关闭——在慢跑动量下定脚看起来正确，但两步一走时会显得戏剧化。    |
| `启用变速片段`      | `布尔值`   | `是`         | —                                     | 在步行和慢跑之间切换时播放过渡片段。集合中需要步行↔慢跑片段。                         |
| `启用速度扭曲`      | `布尔值`   | `是`         | —                                     | 微调片段播放速率以匹配实际移动速度，避免脚滑。                                 |
| `启用脚部 IK`     | `布尔值`   | `是`         | —                                     | 让 Unity 的脚部 IK 将双脚稳定到地面上。                               |
| `启用情绪步态`      | `布尔值`   | `否`         | —                                     | 根据角色当前情绪（由唤醒度推导）缩放指令步行/慢跑速度。默认关闭——一种风格选择。               |
| `情绪步态范围`      | `float` | `0.15`      | `0`–`0.3`                             | 情绪导致的最大速度百分比变化，双向皆然。                                    |

### 过渡与待机

混合需要多久，以及角色切换待机姿势的频率。

| 字段          | 类型               | 默认       | 范围                                  | 说明                                        |
| ----------- | ---------------- | -------- | ----------------------------------- | ----------------------------------------- |
| `待机交叉淡化秒数`  | `float`          | `0.6`    | `>= 0.01`                           | 在不同待机变体之间交叉淡化。                            |
| `待机变体最小间隔`  | `float`          | `8`      | `>= 1`                              | 待机变体在调度器可切换前的最短播放秒数。                      |
| `待机变体最大间隔`  | `float`          | `16`     | `>= 1`, `>= IdleVariantIntervalMin` | 待机变体在调度器切换前的最长播放秒数。                       |
| `动作淡入秒数`    | `float`          | `0.25`   | `>= 0.01`                           | 默认动作/手势淡入；条目可覆盖。                          |
| `动作淡出秒数`    | `float`          | `0.35`   | `>= 0.01`                           | 默认动作/手势淡出；条目可覆盖。                          |
| `动作链交叉淡化秒数` | `float`          | `0.2`    | `>= 0.05`                           | 动作链内部（intro→main→outro）以及同遮罩动作替换时的片段交叉淡化。 |
| `动作层权重`     | `float`          | `1`      | `0`–`1`                             | 播放中的动作在多大程度上替换其下方内容。                      |
| `运动交叉淡化秒数`  | `float`          | `0.25`   | `>= 0.01`                           | 在运动状态之间交叉淡化（待机↔移动、起步、停止、转身）。              |
| `混合曲线`      | `AnimationCurve` | 0→1 缓入缓出 | 必须从 0 变到 1                          | 应用于每个层/状态权重淡出的缓动。缺失或键少于两个时回退到默认缓动曲线。      |

### 高级协同说话

程序化的语音节奏重音。默认关闭；下面的值仅在启用时生效。

| 字段            | 类型      | 默认     | 范围           | 说明                                                                |
| ------------- | ------- | ------ | ------------ | ----------------------------------------------------------------- |
| `启用高级协同说话`    | `布尔值`   | `否`    | —            | 仅根据语音能量包络推导推测性的重音，背后没有语义证据，并且也将这些发布给同伴表演者。角色真正意图的提示始终会发布，不受此设置影响。 |
| `协同说话最小重音能量`  | `float` | `0.42` | `0.1`–`1`    | 语音要有多大声才算重音。                                                      |
| `协同说话强调变化率`   | `float` | `1.2`  | `0.1`–`5`    | 音量上升得多陡峭才会被视为强调。                                                  |
| `协同说话重音概率`    | `float` | `0.48` | `0`–`1`      | 符合条件的时刻实际成为重音的概率。                                                 |
| `协同说话重音不应期秒数` | `float` | `0.85` | `0.3`–`3`    | 两次重音之间的最小秒数。                                                      |
| `协同说话短语能量余量`  | `float` | `0.08` | `0.01`–`0.3` | 音量必须低于运行平均值多少才算短语分隔。                                              |
| `协同说话准备秒数`    | `float` | `0.22` | `0.05`–`0.6` | 重音落下前的蓄势时间。                                                       |
| `协同说话主击打秒数`   | `float` | `0.16` | `0.05`–`0.5` | 重音本身的持续时间，也就是动作中最快的部分。                                            |
| `协同说话指代保持秒数`  | `float` | `0.28` | `0`–`1`      | 重音落下后，姿势保持完全伸展的时间，然后才回稳。                                          |
| `协同说话收回秒数`    | `float` | `0.38` | `0.1`–`1`    | 保持结束后，手臂回收并稳定所需的时间。                                               |

### 集成

此模块发布供其他 Convai 系统消费的信号。

| 字段        | 类型      | 默认  | 范围         | 说明                                                                                 |
| --------- | ------- | --- | ---------- | ---------------------------------------------------------------------------------- |
| `发布用力度`   | `布尔值`   | `是` | —          | 发布一个归一化的运动用力信号（`IExertionSource`）到角色上下文中，以便同伴模块（Body Language 的呼吸）可以消费。若未注册消费者则无害。 |
| `用力度上升秒数` | `float` | `8` | `0.5`–`20` | 持续全速奔跑所需的秒数，使用力度从 0 升至 1。                                                          |
| `用力度恢复秒数` | `float` | `6` | `0.5`–`20` | 角色减速或停止后，用力度从 1 衰减回 0 所需的秒数。                                                       |

### 诊断

该角色运行时向控制台报告多少内容。

| 字段         | 类型         | 默认     | 说明                                    |
| ---------- | ---------- | ------ | ------------------------------------- |
| `跟踪详细程度`   | `动画追踪详细级别` | `关闭`   | 该角色身体动画追踪的控制台/日志详细程度。无论如何，警告和错误始终会记录。 |
| `数据洪流间隔秒数` | `float`    | `0.25` | `>= 0.05` —— 两次 `全量输出`级每帧转储之间的秒数。     |

`动画追踪详细级别` 值，每个都包含其下方所有内容：

| 值      | 整数  | 说明                                                                       |
| ------ | --- | ------------------------------------------------------------------------ |
| `关闭`   | `0` | 无追踪输出。警告和错误仍会记录。随包默认值——一个会走路会说话的角色会产生持续不断的过渡流，而控制台充满例行逐条记录时，真正的警告就容易被忽略。 |
| `状态`   | `1` | 状态机转换、层所有权变更、动作生命周期、片段选择以及启动特性摘要。用于诊断角色行为时应提升到的级别。                       |
| `详情`   | `2` | 增加选择器决策（角度、距离、脚步相位）、带权重的变体随机结果、速度扭曲夹值以及执行器开始/结束标记。                       |
| `全量输出` | `3` | 增加节流后的逐帧层权重和混合位置转储。极其啰嗦；仅用于短时间调试会话。                                      |

### 相关参考

{% content-ref url="/pages/bfa444bd8429ef5ecce69dad819e8a8afcb74544" %}
[身体动画脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/scripting-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/2f6d4e1228a37a16fdb14e3c1941f0d1c8cf7692" %}
[配置移动](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/configure-locomotion.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, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/config-reference.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.