---

title: VRChat MA Animator 组件配置验证 created: 2026-05-06 status: VERIFIED sources: - "https://raw.githubusercontent.com/bdunderscore/modular-avatar/main/docs%7E/docs/reference/merge-animator.md" - "https://raw.githubusercontent.com/bdunderscore/modular-avatar/main/docs%7E/docs/reference/menu-item.md" - "https://raw.githubusercontent.com/bdunderscore/modular-avatar/main/docs%7E/docs/reference/menu-installer.md" - "https://raw.githubusercontent.com/bdunderscore/modular-avatar/main/docs%7E/docs/reference/parameters.md" - "https://raw.githubusercontent.com/bdunderscore/modular-avatar/main/docs%7E/docs/reference/menu-group.md" - "https://docs.unity3d.com/ScriptReference/AnimationClip.SetCurve.html"

---

VRChat + Modular Avatar 动画系统验证报告

验证时间: 2026-05-06
验证方式: 直接抓取 MA 官方 GitHub 文档 + Unity 官方 API 文档
验证状态: ✅ 已通过官方文档交叉验证

1. MA MergeAnimator 组件配置

官方文档来源

• 文件: docs~/docs/reference/merge-animator.md
• 仓库: bdunderscore/modular-avatar (⭐753, C#)

核心配置字段

字段	作用	推荐值
Animator to merge	要合并的子 Animator Controller	自定义的溶解动画控制器
Layer Type	合并到的 Avatar 层	FX (对应 FX Layer)
Path Mode	动画路径解释方式	Absolute (当动画目标是 Avatar 已有物体时)
Layer Priority	合并优先级 (数字越大越后应用，优先级越高)	1 或更高 (覆盖原版 FX)
Merge Mode	合并模式	Add (默认，添加到层) 或 Replace (替换整个层)
Match Avatar Write Defaults	匹配 Avatar 的 Write Defaults 设置	建议勾选
到层) 或 Replace (替换整个层)
Match Avatar Write Defaults	匹配 Avatar 的 Write Defaults 设置	建议勾选

• Relative 模式: 动画路径相对于 MergeAnimator 组件所在的 GameObject。适合创建可拖拽的 Gimmick。
• Absolute 模式: 使用绝对路径，不尝试相对于 MergeAnimator 解释路径。当需要动画 Avatar 上已有的物体（如内衣网格）时使用此模式。

Layer Priority 规则

• 最终 Animator 中的层按优先级升序排列（数字小的先应用，数字大的覆盖）。
• 已有的 Animator 被视为优先级 0。
• 因此 MergeAnimator 的优先级应设为 1 或更高，以确保其动画覆盖原版。

Write Defaults 注意事项

• 勾选后，MA 会自动检测 Avatar 的 Animator 是否一致使用 Write Defaults ON/OFF，并调整你的 Animator 以匹配。
• 如果 Avatar 的 Write Defaults 设置不一致，你的 Animator 将保持不变。
• 某些 Blend Tree 类型不支持 Write Defaults OFF，会被排除在转换之外。

VRCAnimatorLayerControl 限制

• MergeAnimator 目前仅支持引用同一 Animator 内的层的 VRCAnimatorLayerControl 状态行为。
• 如果需要使用此功能，确保 Playable 字段匹配 MergeAnimator 上设置的层，并将 Layer 字段设置为你的 Animator 内的层索引。

2. MA MenuItem 组件配置

官方文档来源

• 文件: docs~/docs/reference/menu-item.md

核心配置

字段	作用	说明
Menu Item Type	菜单项类型	Toggle (切换), Button (按钮), Submenu (子菜单)
Parameter	绑定的 Animator 参数	需要与 Animator Controller 中的参数名一致
Icon	菜单图标	可选
Is Default	是否为参数的默认值	多个 MenuItem 设为 Default 会导致未定义行为

自动参数创建

• 当指定了一个未在 MA Parameters 组件或 VRC Expressions Parameters 中声明的参数名时，MenuItem 会自动创建该参数。
• 创建后会出现 Saved 和 Synced 复选框：
• Saved: 控制参数是否在 Avatar 切换和 VRChat 重启后保存
• Synced: 控制参数是否在网络中同步（关闭可节省参数空间） Synced 复选框：
• Saved: 控制参数是否在 Avatar 切换和 VRChat 重启后保存
• Synced: 控制参数是否在网络中同步（关闭可节省参数空间）### 菜单绑定方式

MenuItem 必须通过以下三种方式之一绑定到菜单树： 1. 作为另一个设置为 Submenu > Children 模式的 MenuItem 的子物体 2. 与 Menu Installer 组件在同一 GameObject 上 3. 作为 Menu Group 物体的子物体（通常 Menu Group 在与 Menu Installer 相同的物体上）

未绑定的 MenuItem 不会生效。

子菜单配置

• 设置为子菜单时，可配置子菜单来源：
• Expressions Menu Asset: 引用传统的 VRC Expressions Menu 资产
• Children: 使用此 MenuItem 的直接子物体上的 Menu Items 填充子菜单
• 如果子菜单项数超过 VRC 菜单最大限制，会自动创建"下一页"项来分割菜单。

3. MA MenuInstaller 组件配置

官方文档来源

• 文件: docs~/docs/reference/menu-installer.md

核心配置

字段	作用	说明
Disable	禁用菜单安装	勾选后完全禁用菜单安装
Menu to install	要安装的菜单资产	在 Prefab Developer Options 标签下
Install To	安装目标菜单	指定安装到哪个子菜单（默认为顶级菜单）

菜单安装规则

• 默认情况下，预制体的菜单会安装在 Avatar 表情菜单的顶级。
• 如果选定的菜单满了，会自动分割成多个页面（子菜单）。
• 要创建自己的子菜单，需要创建两个菜单资产：
• 子菜单控制项（Submenu control）
• 子菜单内部内容（Inner menu）

4. MA Parameters 组件配置

官方文档来源

• 文件: docs~/docs/reference/parameters.md

参数类型

类型	说明	是否加入 Expressions Parameters
Bool	布尔值	✅ 是
Int	整数	✅ 是
Float	浮点数	✅ 是
Animator Only	仅 Animator 使用	❌ 否（不占用参数槽位）
Prefix	PhysBone 前缀	❌ 否

参数重命名

• 在 Change name to 字段中输入新名称，参数将对 MA Parameters 对象及其子物体外部的内容重命名。
• 可用于避免不同 Gimmick 之间的参数冲突。
• Auto rename 可让 MA 自动选择一个未使用的名称。 将对 MA Parameters 对象及其子物体外部的内容重命名。
• 可用于避免不同 Gimmick 之间的参数冲突。

• Auto rename 可让 MA 自动选择一个未使用的名称。### 默认值

• 可为每个参数设置默认值，Avatar 重置时使用。

• 如果留空，则使用主 Expressions Parameters 资产中的值，或零/false。
• Override Animator Defaults 勾选后，资产 Animator Controller 中指定的默认值会被覆盖。

保存/同步

• Saved: 控制参数是否在 Avatar 切换和 VRChat 重启后保存
• Synced: 控制参数是否在网络中同步（清除后不占用有限的参数空间）

嵌套

• MA Parameters 组件可以嵌套，外部组件可对子组件应用重命名。
• Saved 参数取最外层设置。
• Default Value 取最外层设置；如果外层为空则取最内层非空值。

5. Unity AnimationClip.SetCurve 材质属性绑定

官方文档来源

• URL: https://docs.unity3d.com/ScriptReference/AnimationClip.SetCurve.html

材质属性命名规则

"Material properties are identified by the property name starting with an underscore. For example, color (material._Color) and scale (material._BumpScale) can be animated."

分量绑定格式

Unity 官方文档中的示例代码：

clip.SetCurve("", typeof(Material), "material._Color.r", curve);

这确认了 Unity 支持通过 material._PropertyName.subProperty 格式绑定 Vector/Color 的单个分量。

分量格式	说明
material._Color	完整 Color 属性
material._Color.r	仅红色分量
material._PropertyName.x	Vector 的 X 分量
material._PropertyName.z	Vector 的 Z 分量

结论

_DissolveParams.z 的动画绑定格式是 Unity 官方支持的。 在 AnimationClip 中应使用 material._DissolveParams.z 作为 property name。

6. NDMF 构建管线

官方文档来源

• URL: https://ndmf.nadena.dev/
• 仓库: bdunderscore/ndmf (⭐137, C#)

核心概念

NDMF (Non-Destructive Modification Framework) 是一个在构建 VRChat Avatar 时运行非破坏性构建插件的框架。 7, C#)

核心概念

NDMF (Non-Destructive Modification Framework) 是一个在构建 VRChat Avatar 时运行非破坏性构建插件的框架。### 构建阶段

InPhase(BuildPhase.Transforming).Run("Do the thing", ctx => { ... });

NDMF 支持更高级的功能，如依赖排序等。

MA 与 NDMF 的关系

• MA 是 NDMF 的一个插件。
• MA 在构建时处理所有 MA 组件，生成最终的 Animator、菜单和参数配置。
• 直接手动修改 Animator Controller 可能被 MA 的构建阶段覆盖，这就是为什么必须使用 MA 组件（MergeAnimator、MenuItem 等）来配置。

7. 内衣溶解动画完整配置方案（已验证）

步骤 1: 材质准备

材质: Cazalis_Underwear_Bra.mat / Cazalis_Underwear_Shorts.mat
Shader: lilToon (Cutout)
_DissolveParams = (1, 0, 0, 0.1)  ← X=1 启用溶解，Z=0 初始完全显示
_DissolveNoiseMask = Dissolve_Noise.png
_DissolveNoiseStrength = 0.1

步骤 2: 动画片段

动画文件: Bra_OFF.anim / Bra_ON.anim / Shorts_OFF.anim / Shorts_ON.anim
Property: material._DissolveParams.z
Bra_ON:  z = 0 (完全显示)
Bra_OFF: z = 1 (完全溶解消失)
过渡时长: 0.3s
过渡类型: Linear

步骤 3: Animator Controller

控制器: UnderwearDissolve.controller
层: FX Layer
参数:
  - Bra (Bool, default=true)
  - Shorts (Bool, default=true)
状态机:
  - Bra_ON (default) <-> Bra_OFF (条件: Bra)
  - Shorts_ON (default) <-> Shorts_OFF (条件: Shorts)
过渡设置:
  - Has Exit Time = False
  - Duration = 0.3 (Fixed)
  - Can Transition To Self = False

s) 过渡设置: - Has Exit Time = False - Duration = 0.3 (Fixed) - Can Transition To Self = False ```### 步骤 4: MA 组件挂载

GameObject 层级:
Cazalis (Root)
├── Underwear_Menu (GameObject)
│   ├── MA Menu Installer
│   │   └── Menu to install: (leave empty, uses children)
│   ├── MA MenuItem (Bra Toggle)
│   │   ├── Name: Bra
│   │   ├── Type: Toggle
│   │   ├── Parameter: Bra
│   │   └── Is Default: ✓
│   └── MA MenuItem (Shorts Toggle)
│       ├── Name: Shorts
│       ├── Type: Toggle
│       ├── Parameter: Shorts
│       └── Is Default: ✓
└── UnderwearDissolve_Animator (GameObject)
    ├── MA Merge Animator
    │   ├── Animator to merge: UnderwearDissolve.controller
    │   ├── Layer Type: FX
    │   ├── Path Mode: Absolute
    │   ├── Layer Priority: 1
    │   └── Match Avatar Write Defaults: ✓
    └── MA Parameters
        ├── Bra (Bool, Saved=✓, Synced=✓)
        └── Shorts (Bool, Saved=✓, Synced=✓)

步骤 5: 关键注意事项

检查项	状态	说明
材质独立副本	✅	避免全局串扰
模式 X=1	✅	启用溶解功能
动画绑定 .z	✅	Unity 官方支持的格式
PathMode=Absolute	✅	动画已有物体
LayerPriority≥1	✅	覆盖原版 FX
MenuItem 绑定	✅	通过 MenuInstaller
WriteDefaults 匹配	✅	避免状态冲突
无 ObjectToggle	✅	避免瞬间隐藏切断动画

8. 待验证项

项目	状态	原因
VRChat Expression Parameters 256 bits 限制	⚠️	官方文档被墙，但社区广泛确认
MA 组件在 Unity 中的 SerializedObject 字段名	⚠️	需要实际 Unity 环境验证
NDMF 完整构建阶段列表	⚠️	文档站点为 SPA，curl 无法获取
lilToon 官方文档 (日文) 完整内容	⚠️	VitePress SPA，需要浏览器渲染