动画器参数
本文档需要了解 Unity 的 Animator Controller 和 动画参数。
你可以在虚拟形象的可播放层中使用动画器参数来控制或影响虚拟形象的动画器状态。
你应该假设参数随时可能发生变化。避免"死胡同"——如果你的状态没有出口，虚拟形象的动画器可能会出问题。
内置参数
你可以通过将参数添加到虚拟形象的可播放层来 访问 VRChat 的内置虚拟形象参数。
如果你添加了这些参数之一，VRChat 会根据 VRChat 中发生的事情自动更新其值。例如，如果你添加了 VelocityMagnitude 参数，其值会根据玩家的当前速度更新。
所有内置参数都是只读的。你不能通过表情菜单或 OSC 更改它们。
下面的列表包含了 VRChat 的所有内置参数、描述、类型和同步类型。
| 名称 | 描述 | 类型 | 同步类型 |
|---|---|---|---|
| IsLocal | 如果虚拟形象是本地穿戴的则为 True，否则为 False | Bool | None |
| PreviewMode | 如果虚拟形象正在预览中则返回 1，否则返回 0 | Int | None |
| Viseme | Oculus viseme 索引（0-14）。使用颌骨/颌动时，范围是 0-100，表示音量 | Int | Speech |
| Voice | 麦克风音量（0.0-1.0） | Float | Speech |
| GestureLeft | 左手控制手势（0-7） | Int | IK |
| GestureRight | 右手控制手势（0-7） | Int | IK |
| GestureLeftWeight | 左扳机键模拟值（0.0-1.0）1 | Float | Playable |
| GestureRightWeight | 右扳机键模拟值（0.0-1.0）1 | Float | Playable |
| AngularY | Y 轴角速度 | Float | IK |
| VelocityX | 横向移动速度（米/秒） | Float | IK |
| VelocityY | 垂直移动速度（米/秒） | Float | IK |
| VelocityZ | 前向移动速度（米/秒） | Float | IK |
| VelocityMagnitude | 总速度大小 | Float | IK |
| Upright | 你的"直立"程度。0 为俯卧，1 为笔直站立 | Float | IK |
| Grounded | 玩家接触地面时为 True | Bool | IK |
| Seated | 玩家在载具中时为 True | Bool | IK |
| AFK | 玩家是否不可用（HMD 接近传感器 / End 键） | Bool | IK |
| TrackingType | 见下方描述 | Int | Playable |
| VRMode | 如果用户在 VR 中则返回 1，否则返回 0 | Int | IK |
| MuteSelf | 如果用户已将自己静音则返回 true，否则返回 false | Bool | Playable |
| InStation | 如果用户在载具中则返回 true，否则返回 false | Bool | IK |
| Earmuffs | 如果用户的 Earmuff 功能开启则返回 true，否则返回 false | Bool | Playable |
| IsOnFriendsList | 如果查看虚拟形象的用户与穿戴者是好友则返回 true。本地为 false。 | Bool | Other |
| AvatarVersion | 如果虚拟形象是使用 VRChat SDK3（2020.3.2 或更新版本）构建的则返回 3，否则返回 0。 | Int | IK |
| IsAnimatorEnabled | 在虚拟形象动画器被禁用前一帧返回 false，启用时返回 true。 | Bool | None |
虚拟形象缩放参数
你的可播放层可以通过以下参数对玩家当前的虚拟形象缩放做出反应：
| 名称 | 描述 | 类型 | 同步类型 |
|---|---|---|---|
| ScaleModified | 如果用户使用了虚拟形象缩放则返回 true，如果虚拟形象处于默认大小则返回 false。 | Bool | Playable |
| ScaleFactor | 虚拟形象默认高度与当前高度之间的比率。默认眼睛高度为 1m 缩放到 2m 的虚拟形象将报告 2。 | Float | Playable |
| ScaleFactorInverse | 虚拟形象默认高度与当前高度之间的反比率（1/x）。默认眼睛高度为 1m 缩放到 2m 的虚拟形象将报告 0.5。在极端情况下可能不准确。 | Float | Playable |
| EyeHeightAsMeters | 虚拟形象的眼睛高度（以米为单位）。 | Float | Playable |
| EyeHeightAsPercent | 虚拟形象眼睛高度相对于默认缩放限制（0.2-5.0）的比率。缩放到 2m 的虚拟形象将报告 (2.0 - 0.2) / (5.0 - 0.2) = 0.375。 | Float | Playable |
参数类型
你可以在表情参数资源中定义以下参数类型：
| 参数类型 | 范围 | 参数内存使用量 | 备注 |
|---|---|---|---|
int | 0-255 | 8 位 | 无符号 8 位整数。 |
float | -1.0 到 1.0 | 8 位 | 有符号 8 位定点小数2。 |
bool | True 或 False | 1 位 |
每个同步参数使用一定量的参数内存。VRChat 最多可以同步 256 位的自定义参数。VRChat 还限制你的虚拟形象最多有 8192 个自定义表情参数（同步和未同步）。内置参数不计入这些限制。
GestureLeft 和 GestureRight 值
GestureLeft 和 GestureRight 使用以下值：
| 索引 | 手势 |
|---|---|
| 0 | 中性（Neutral） |
| 1 | 拳头（Fist） |
| 2 | 手掌张开（HandOpen） |
| 3 | 手指指向（FingerPoint） |
| 4 | 胜利（Victory） |
| 5 | 摇滚（RockNRoll） |
| 6 | 手枪（HandGun） |
| 7 | 大拇指（ThumbsUp） |
Viseme 值
我们使用 Oculus viseme 索引，从上到下，其中 sil 为 0。供参考：
| Viseme 参数 | Viseme |
|---|---|
| 0 | sil |
| 1 | pp |
| 2 | ff |
| 3 | th |
| 4 | dd |
| 5 | kk |
| 6 | ch |
| 7 | ss |
| 8 | nn |
| 9 | rr |
| 10 | aa |
| 11 | e |
| 12 | i |
| 13 | o |
| 14 | u |
AFK 状态
AFK 状态由以下情况触发：
- 用户摘下头显，HMD 接近传感器返回头显未被佩戴
- 系统菜单打开。这取决于你使用的平台在系统菜单打开时如何传送数据——例如，Oculus Dash 不会注册为 AFK，但 SteamVR 的菜单会注册为 AFK。这有点像附带影响，并非有意设计的行为。
- 用户按下了 End 键，切换了 AFK 状态。
TrackingType 参数
TrackingType 指示一些信息。
如果 VRMode 为 1 时值为 3、4 或 6，则表示虚拟形象穿戴者启用并当前追踪的追踪点数量。这个值可能会改变！ 如果一个使用 6 点追踪的用户移除了额外的三个追踪点，该值将从 6 变为 3。在设计动画器时请考虑到这一点。
如果 VRMode 为 1 时值为 0、1 或 2，则表示虚拟形象仍在初始化中。你不应该设计动画器根据这些值的组合进行分支，而应该等待"有效"值 3、4 或 6。
在虚拟形象初始化期间，此值可能会改变！确保你的动画器考虑到可能的变化，并且不会"死胡同"地进入任何分支。
| 参数 | 描述 |
|---|---|
| 0 | 未初始化。通常仅在用户切换虚拟形象且其 IK 尚未发送时发生。 |
| 1 | 通用骨骼。用户可能开启了任何类型的追踪，但虚拟形象绑定为 Generic，因此追踪被忽略。如果 VRMode 为 0，则_可能_是桌面用户。 |
| 2 | 仅出现在 AV2 中，因此对于 AV3 控制器来说，你不应该期望长时间处于此状态。可能仍会出现在 SDK3 载具中。 仅手部追踪，无手指。这只会出现在过渡状态中——也就是说，你应该预期 TrackingType 会再次改变，虚拟形象不应停留在此状态。 |
| 3 | 头部和手部追踪。如果 VRMode 为 1，此用户处于 3 点 VR。如果 VRMode 为 0，这是一个使用人型虚拟形象的桌面用户。 |
| 4 | 4 点 VR 用户。头部、手部和臀部。 |
| 5 | 5 点 VR 用户。头部、手部和脚部追踪。基本上是全身追踪但没有臀部。 |
| 6 | 全身追踪 VR 用户。头部、手部、臀部和脚部追踪。 |
自定义参数
你可以向虚拟形象的可播放层添加自己的参数。
你必须创建一个表情参数资源，这允许你在 VRChat 中控制参数。例如，你可以设置一个表情菜单，允许用户在 VRChat 中自定义你的虚拟形象。
表情参数资源
表情参数资源包含你的可播放层可以使用的自定义参数列表。每个参数都有一个名称、类型和默认值。你还可以选择参数是否应与其他玩家同步，这允许其他玩家看到由动画器和自定义参数引起的变化。
通过阅读表情菜单文档，了解如何创建表情参数资源。
如何控制自定义参数
在你的虚拟形象的可播放层和表情参数资源中设置好自定义参数后，你可以通过三种不同方式控制它们：
- 设置一个表情菜单，允许用户在 VRChat 中轻松控制参数，例如在服装之间切换或播放自定义动画。表情菜单是控制自定义参数最简单、最常用的方法。
- 你可以将状态行为虚拟形象参数驱动器附加到可播放层的状态上。它可以自动设置、添加或随机化你在表情参数资源中定义的参数。
- 你可以为 OSC 设置虚拟形象，允许用户和第三方工具控制参数。例如，VRCFaceTracking 使用面部和眼部追踪硬件来控制虚拟形象的面部表情参数。
默认 AV3 别名
模板 AV3 VRChat 控制器使用了一些"默认值"，如果你不想构建自己的控制器，可以使用它们。由于别名的存在，它们不会与你自己的使用冲突（只要你不将它们命名为相同的名称）。
特别是，默认的 Action 和 FX 层使用了别名。你不需要担心使用这些层中的表情。
Action 层使用别名为 VRCEmote 的参数，这是一个范围在 1 到 16 之间的 Int。
FX 层使用别名为 VRCFaceBlendH（-1,1）和 VRCFaceBlendV（-1,1）的 Float 参数，如果你想尝试使用自己的菜单来使用它们。默认的 FX 层要求你有一个名为 Body 的蒙皮网格，其中包含 mood_happy、mood_sad、mood_surprised 和 mood_angry blendshape。
重申一下，如果你有一个作为 Avatar3 虚拟形象上传但没有自定义可播放层的虚拟形象，只要你有上述命名的 blendshape，你就可以使用一些内置表情。
如果你还有一个 eyes_closed blendshape，当你使用默认的死亡表情或进入 AFK 状态时，它会闭上眼睛。
跨平台参数同步
当使用同时上传了 Quest 和 PC 版本的虚拟形象时，参数是根据其在参数列表中的位置和参数类型进行同步的，而不是根据参数名称。要使某个参数在 PC 和 Quest 之间同步，它必须位于参数列表中的相同位置，并且具有相同的参数类型。
因此，你应该始终对虚拟形象的 PC 和 Quest 版本使用相同的表情参数资源，即使某个版本没有使用所有参数。
不匹配的参数类型转换
当你在动画器中选择参数类型时，最好选择与你要使用的内置参数或自定义参数相同的类型。例如：如果你在动画器中使用 VRChat 的内置 AFK 参数，你应该选择 bool 类型。
但是，你可以为参数选择不匹配的类型。VRChat 会尝试将参数值转换为动画器使用的类型。例如，如果你选择 float 类型作为 AFK 参数，VRChat 会自动将 AFK 设置为 1.0 或 0.0，而不是 true 或 false。这也允许你在动画器的混合树中使用 AFK 参数。
下表显示了转换不匹配参数时的变化方式。
| 源类型 | 动画器类型 | 转换行为 | 示例 |
|---|---|---|---|
int | float | 直接转换为 float。 | 1 → 1.0 |
int | bool | 0 为 false，其他所有值为 true | 1 → true |
float | int | 四舍五入到最接近的 int（与 Mathf.Round 相同） | 0.5 → 0, 0.6 → 1, 1.5 → 2 |
float | bool | 0.0 为 false，其他所有值为 true | 0.5 → true |
bool | int | true 为 1，false 为 0 | true → 1 |
bool | float | true 为 1.0，false 为 0.0 | true → 1.0 |
触发器类型参数
目前我们不建议在你的动画控制器中使用 Trigger 类型参数。这些值可能会在虚拟形象的不同版本之间失去同步，包括远程客户端查看你的虚拟形象，或在特殊情况下如查看镜像中的虚拟形象。如果你要表示虚拟形象的状态，请使用 Int、Float 或 Bool 类型的参数。
同步类型
VRChat 会将大多数内置参数与实例中的其他玩家同步，你也可以为你自己的自定义参数启用同步。
同步类型决定了 VRChat 如何同步每个参数。参数使用以下同步类型之一：
- Speech
- 仅用于 viseme。
- 根据你的语音驱动 Oculus Lipsync 输出参数。
- 在本地更新，不直接同步（因为由音频驱动）
- Playable
- 一种较慢的同步模式，用于同步持续时间较长的动画状态。
- 根据参数变化每 0.1 到 1 秒更新一次（每秒 1 到 10 次更新），但你不应依赖它进行快速同步。
- IK
- 一种更快的同步模式，用于同步频繁变化的值。
- 每 0.1 秒持续更新（每秒 10 次更新），并在本地为远程用户插值
float值。 - 根据参数的不同，这也可能只是根据虚拟形象本地渲染的 IK 状态计算得出的。
- None
- 此参数不会与其他玩家同步。
- 例如，
IsLocal对于本地玩家的虚拟形象始终为 true，对于其他玩家的虚拟形象始终为 false。
如果你为自定义参数启用同步，VRChat 通常使用 Playable 同步类型。但是，当你使用 Puppet 控件控制参数时，VRChat 会从 Playable 切换到 IK 同步，从而改善更新速率和平滑插值。当你关闭 Puppet 控件时，它会恢复为 Playable 同步。