scenario-maya-fx

Maya 特效（Nucleus、Bifrost、MASH、缓存）

资深特效 TD 会先修正比例和输入，再调整参数；每次只改少量设置；绝不对实时求解结果妄下判断；并通过缓存中的数值（穿透、拉伸、跳帧、收敛）以及镜头相机的渲染来验证结果。如果这里提到的同级技能不在可用技能中，请让用户安装 （npx skills add scenario-labs/skills --skill <name>）；若无人值守，则根据工具模式继续操作，并指出缺失之处。

必需背景： scenario-maya-expert（执行渠道、审查循环、2027 版本陷阱）。

状态（2026-09-24）： 尚未安装 Maya 2027。纯 Python 层 scripts/mx_fx.py 已通过离线测试（tests/code/maya-fx/test_fx_offline.py）； 所有 Maya 调用尚未在 Maya 中运行；标记为 [verify] 的名称由 job_00_fx_probe.py 解答（python3 tests/code/maya-fx/run_all.py）。

原则（专家要点）

• 先处理比例。 无论 Maya 使用什么单位，Nucleus 和 Bifrost 都以米为单位计算：在厘米场景中，Space Scale 和 scene_units_in_meters 应为 0.01；否则，182 cm 的角色对求解器来说就是 182 m（2027 Help；SARKAMARI [00:29:22]；Stamatelos [00:30:21]）。MPM 的 detail_size 以米为单位，因此更改单位会悄然改变分辨率（Gast [00:07:29]）。
• 绝不模拟生产网格。 复制蒙皮后的身体和服装，用权重为 1 的混合变形驱动副本，并隐藏原始对象（SARKAMARI [00:10:04]）。
• 让求解器从干净状态开始。 保持 25 帧，将首个姿势混合 25 帧，在第 0 帧开始动作，Nucleus 起始帧设为 -50（SARKAMARI [00:05:26]）；Julan：第 0 帧为 A 姿势，第 24 帧前开始行走。
• 先增加子步，再调刚度。 碰撞迭代次数低于子步数时不起作用；子步数过低时，较高的拉伸阻力无法收敛（2027 Help，Tips）。SARKAMARI 在同一轮中将 Space Scale 调至 0.25，子步数设为 30、迭代次数设为 35 后，残余穿透消失 [00:29:22] [00:29:57]。
• 缓存、评估缓存、渲染缓存。 每次 playblast 前都创建 nCache；渲染场景中只保留 Alembic（SARKAMARI [00:19:32]、[00:40:07]）。
• Bifrost 会静默失败。 未连接到输出的内容永远不会计算；空数组是有效数据；数组长度不匹配时会截断（Jason E3aOt5wuvoo [00:22:49]；Nordenstam [00:38:11]；图表文档）。模拟只能从自身的起始帧向前求解：默认为第 1 帧，而且该帧必须位于时间轴中（模拟指南；Nordenstam [00:56:23]）。
• 不要模拟不需要的内容。 让雪球从碰撞体处开始，并赋予其撞击速度（Gast [00:55:18]）；通过 Alembic 碰撞体分层模拟服装（SARKAMARI [00:32:06]）；背景源使用粗略设置（Stamatelos [00:21:25]）。
• 每次运行只改一项，并记录日志（Jason cd3HgvM8sXg [00:21:43]）；mx_fx.set_attrs 会返回日志。

首先确认

输入	为什么会改变计划	未说明时的默认值
镜头帧范围、帧率、动作起始帧	预滚动、缓存范围、余量帧	24 fps，动作开始前预滚动 50 帧
角色交付方式	模拟副本需要绑定骨骼或缓存的角色身体	引用 scenario-maya-animation 中的绑定角色或 Alembic
线性单位和实际尺寸	求解器缩放	cm，使用 mx_fx.scale_report 检查实际尺寸
目标用途	影视（Arnold、VDB、Alembic）与游戏（精灵、烘焙网格、USD）	Arnold 影视
摄像机和运动模糊	可接受的穿透程度	镜头摄像机，开启模糊
布料或材质	预设、刚度	披风：厚牛仔布参数［新增选择］；尘土：Aero 平滑
预算	子步数、分辨率、每帧模拟时间	初次模拟 10/12，细节 0.1；最终 30/35

工作流

1. 缩放和输入。 mx_fx.scale_report(meshes, expected_size_m=...)；如果模型尺寸不符合实际， 修正资产（Julan［00:02:02］）。使用 art_choice=True 记录任何有意采用的非物理缩放（SARKAMARI 对 182 cm 角色采用 0.25）。检查点：没有错误行。

2. 选择系统（根据需求选择）：

   效果	默认	替代方案及适用情况
   披风、角色身上的服装	nCloth	必须撕裂、在 Bifrost 图中运行，或通过 USD 用于游戏时，使用 Bifrost MPM 布料（Jason hmuWr2nWSms、yo6y7cANfX0）
   尘土团、烟雾、薄雾	Bifrost Aero	为泥土团块添加 MPM 沙土或雪；使用 nParticles 制作砂砾（仅文档级）
   雪、沙土、泥浆冲击	MPM 颗粒	来源中没有替代方案
   散布、复制品群集、动态图形	MASH（Repro）	追求速度时使用 Instancer；对 USD 点实例化使用 Bifrost scatter_points
   液体	basic_liquid_graph	旧版 Bifrost Fluids 已不再提供

3. 准备布料输入。 拓扑门控 mx_fx.cloth_topology_verdict(mx_audit.audit(garment), expected_border_loops=1)：四边形均匀分布（交叉链接需要四边形）、流形、单面、孔洞已封闭（SARKAMARI [00:03:05]）。 预先滚动 mx_fx.add_preroll(ctrls, action_start, rest=bind_pose)；在绑定帧使用 mx_fx.sim_duplicate 进行复制。门控：判定结果无问题，副本与原件的偏差在 0.01 cm 以内。

4. 构建。

   • nCloth：mx_fx.build_cloth_rig(garment_SIM, body_SIM, action_start, preset=...)：一个 nucleus， 根据单位设置 Space Scale，从预先滚动帧开始，首轮使用 10 个子步／12 次迭代，采用预设 值，使用薄布料和碰撞体。使用输入吸引锁定贴图固定斗篷领口（值为 1，并将 Input Attract Method 设为“Lock values of 1.0 or greater”，Collide Last Threshold 设为 1.0，[新增] 文档中的方案），或者使用 Point to Surface 并启用 Exclude Collisions（SARKAMARI [00:23:40]）； 成员需位于输入网格上（文档指出，输出网格成员可能导致 DG 循环； point_to_surface(..., cloth=) 会重写成员）。门控：rig["verdict"] 无错误。
   • Bifrost：从 basic_*_graph 和 Explode 开始（Stamatelos [00:39:07]）；使用 mx_fx.BifrostGraph 编写脚本（记录每次 VNN 调用），或复用 GUI 的 Echo All Commands 日志。隐藏导入的对象（Jason）。开放或平坦的发射器（圆环、地面补片）需要 Shell，封闭发射器需要 Solid（Stamatelos [00:10:40]）。设置模拟的起始帧。门控：对 emitter_facts(mesh) 调用 aero_source_verdict(...)，并调用 sim_range_verdict(...)，结果均无问题；所有输出都已拉取；每一帧的点数或体素数均大于 0。
   • MASH：mx_fx.mash_network(sources, geometry="Repro") [验证 MASH.api]。源对象大小为单位尺寸（Waters）。门控：读取 mx_fx.mash_cache_reasons(mx_fx.mash_inventory(waiter))。

5. 先低成本跑首轮，再缓存。 使用低分辨率（Aero detail 0.1、布料首轮设置），从起始帧开始按顺序评估帧（mx_fx.run_sim、step_frames），并在 GUI 中播放每一帧。更改 geo_detail_size 或 time_step_size，或创建或分解复合体后，均需从头重新运行（模拟指南）。门控：没有非有限值，也没有空帧。

6. 测量并查看。 rep = mx_fx.sim_report(cloth_out, body_SIM, start, end, action_start=..., thickness=...)， rep["convergence"] = mx_fx.convergence_test(...)，mx_fx.sim_verdict(rep, budget_spf=...) （添加文档中的 Timing Output 门控：根据需求说明检查每帧求解秒数）。然后查看： 无头模式下使用 mx_review.review([cloth_out, body_SIM], out, views=("side","back","threequarter"), modes=("clay",), focus=fixed) 查看动作起始帧、峰值帧和最后一帧；使用 GUI 中的 mx_review.playblast 从镜头摄像机生成预览； 使用 mx_fx.volume_review 查看体积（Arnold、tricubic）。根据 references/critique.md 进行评估。

7. 按此顺序排查问题（绝不要先增加刚度）：缩放；起始状态（预先滚动、Push Out、带 Trapped Check 的 Crossover Push）；在迭代次数高于子步数的前提下增加子步数；降低厚度，提高 Self Collide Width Scale；同时调整拉伸和压缩（SARKAMARI [00:24:50]）；翻转时使用 Bend Solver High Quality；吸引或刚性约束将布料拖穿时，将 Collide Last Threshold 设为 1.0；降低弹跳约束的 Strength；“frame change too large”表示应从头播放或进行缓存（2027 Help）。 对于残留的穿插：在缓存后的网格上雕刻修正，或接受其在模糊效果下的表现（SARKAMARI [00:37:12]）。Aero detail：使用 2027 的锐化功能（aero_refinement_settings，数值较低）、自适应范围，或在降低所有位置的 detail size 之前，对缓存使用 post_refine_aero（按帧顺序处理，使用原始源对象和碰撞体）（模拟指南）。

8. 完成最终缓存并交付。 使用最终通道设置，从 nucleus 起始帧开始创建 nCache （ncache_verdict：mcc 达到 2 GB 后会停止，请使用 mcx；仅缓存位置，因此布料变换必须保持静止），禁用 nucleus；在镜头范围内导出包含 UV 和颜色集的布料与身体 Alembic（mx_fx.alembic_export）；Bifrost file_cache 仅缓存渲染器需要的属性；创建仅包含缓存的渲染场景。门控：mx_fx.alembic_check 和 file_sequence_report 结果无问题，并查看缓存。

数值

数值	相对于	来源
空间比例，scene_units_in_meters 0.01	cm 场景	2027 Help；Stamatelos
Nucleus 3 / 4（预设），首次通过 10 / 12，最终 30 / 35	子步数 / 最大碰撞迭代次数	文档；SARKAMARI
预滚动保持 25 + 混合 25，开始于 -50	在 0 处执行动作	SARKAMARI
长裤摩擦力 0.1、拉伸 80、压缩 20、阻尼 0.4 后改为 0.2、质量 0.8	T 恤预设 0.3 / 35 / 10 / 0.8 / 0.6	SARKAMARI；文档
宽松衬衫拉伸 40、压缩 15、质量 0.2、阻尼 0.3	相同	SARKAMARI
静止长度 0.9（紧绷），0.5（起皱）；吸引 0.7 [?]（领口）	绘制区域	SARKAMARI
碰撞最后阈值 1.0（默认 0.2）	使用吸引或刚性时	文档
空气环境值 20、源值 580、浮力 -9.81	上升由差值产生	Stamatelos
空气细节 0.1（预览）、0.05（默认）、0.025（精细）	绝对模式（世界单位）；相对模式保持体素数量不变	Jason；Stamatelos
MPM initial_firmness 约为速度的平方（10 m/s：100）	冲击速度	Gast
MPM 布料面积保持 0.1（0 = 最硬），振动速度 +10 步，碰撞最大速度约为一半	布料	Jason
精灵 64 帧 x 512 px，4096 上为 8 x 8；SDF 密度为 0.005	翻页动画	Jason

质量门槛

• 代码检查： cloth_topology_verdict、scale_report、nucleus_verdict（迭代次数高于子步数、比例、预滚动）、sim_verdict（动作后穿透顶点为零、拉伸低于静止长度的 1.10 x [新增]、弹跳、稳定、间距、收敛、求解时间）、alembic_check（范围、单个网格、顶点数）、file_sequence_report（每一帧、无失控增长）、sim_range_verdict（缓存和审查范围到达镜头末尾）、ncache_verdict、mash_cache_reasons、overlaps（实例）、sprite_framing、usd_check_unreal。
• 视觉检查： 角色以目标速度运动时，布料的重量感和摆动是否与参考一致、褶皱、腋下和背面视图在平滑预览下的效果、领口硬度、服装是否留在肩部、镜头中是否能看到穿透或被模糊隐藏（SARKAMARI [00:36:39]、[00:37:46]）；烟雾是否上升、散开、消散，是否没有体素消失、阶梯状轨迹或与碰撞体之间的间隙，并在渲染中进行判断（Stamatelos；模拟指南）；MPM 裂纹形态、碎块尺寸、碎屑；拖动变形网格时 MASH 是否抖动（Waters [00:03:53]）。

常见错误

错误	表现	修复方案
在以厘米为单位的场景中使用 Space Scale 1	布料缓慢飘浮，像巨型布料	设为 0.01，或记录为美术选择
迭代次数小于或等于子步数	增加额外步骤没有任何变化	迭代次数大于子步数
没有预模拟，模拟从动作开始时启动	第 1 帧发生爆炸或穿插	保持并混合，开始帧设为 -50
Alembic 范围从 nucleus 开始帧之后开始	求解器跳变，布料弹出或冻结 [added, verify]	先缓存，或从开始帧导出
自碰撞使用较厚的布料	布料膨胀，悬离身体	使用较薄的布料，设置 Self Collide Width Scale
Bifrost 输出未连接	对象消失，没有错误	将反馈和调试节点连接到输出
从模拟开始帧之后的帧开始步进，或开始帧在时间轴范围之外	前几帧没有求解，或什么都没有发生	从开始帧步进（sim_range_verdict）
使用绝对分辨率且细节尺寸较小	体素数量激增，Maya 卡死	使用 Relative，或在预算范围内使用 aero_source_verdict 估算（Stamatelos [00:12:48]）
灰尘源温度过高	像羽流一样上升，而不是扩散	温度设为环境温度 20，设置初始速度和继承速度 [added from Stamatelos' knobs]
均匀的烟雾源	凸凹不平的蘑菇云	使用 vary_source_property、噪声变形发射器、湍流、耗散（Jason）
大型地面的相对碰撞体细节	烟雾或雪下方出现间隙	减小碰撞体细节，使用 link_collider_detail（MPM）
MPM 固定点加上直接连接的 make-to-simulate	布料被模拟了两次	移除直接连接
在绑定网格上进行基于面面积的 MASH 散布	点抖动	使用 Mesh from Points，绑定，复制权重，Vertex + Flood
动画化 Time Scale，但未使用 Simulated Time	追赶式爆发	使用 Simulated Time，然后烘焙

交接

• **接收自 scenario-maya-animation：**角色的引用绑定或 Alembic、已批准的镜头帧范围和 fps、可用的绑定姿势（用于预卷）、validate(profile="shot") 通过。若时间轴从动作开始处起步，则要求在动作前留出预卷空间。
• **交付给 scenario-maya-lighting-rendering：**仅包含缓存的新场景版本 <shot>_fx_render_v###.ma；Alembic <asset>_<fx>_v###.abc（包含 UV、颜色集、镜头帧范围及 handles）以及发生碰撞的物体（SARKAMARI [00:39:34]）；仅含密度和速度的 VDB 序列（火焰还需包含温度）；用于恢复工作的 Bifrost 缓存 .bob；sim_report.json、已查看的审阅表或 playblast，以及尚未验证的内容。单位为 cm，Y 轴向上；注明帧范围。
• **交付给 scenario-maya-pipeline-scripting（游戏）：**flipbook 通道（emission、volume_direct、tangent-space normals），且 sprite_framing 通过检查；经 usd_check_unreal 检查的烘焙 Alembic 或 USD 网格；适用于引擎的低分辨率版本（Jason yo6y7cANfX0 [00:05:09]）。
• 若渲染主体是开放或高面数的，向 scenario-maya-rigging 请求封闭、简化的碰撞体代理。

Maya 2027 注意事项

• 始终安装 Bifrost 3.0（2027.1 中为 3.1.0.8）；支持异步求值、Batch Execute 和 Write State，以及节点搜索。旧版 Bifrost Fluids 已移除：使用 basic_liquid_graph。
• MPM 2027：link_collider_detail、max_voxel_movement 重试、lag_colliders、initial_firmness。
• Bifrost 文档中的名称不一致（simulate_liquid(s)、liquid_solver_settings 与 _properties、同时适用于 Solid/Shell 和 Absolute/Relative 的 geo_volume_mode）：使用 BifrostGraph.find_port 读取端口。
• nCloth Bend Solver 默认设为 High Quality。Cached Playback 可以在内存中缓存动力学；交接时仍使用磁盘上的文件。
• MASH：Signal 替代 Noise 和 Trig，Strength 替代 Mute，节点作用于 TRS，Repro 为默认设置，Delay 会偏移变换动画。
• Alembic 仅支持 Ogawa。AbcExport 的 -j 字符串会按空格拆分［新增，待验证］：alembic_export 会先写入不含空格的临时路径。

参考资料

• references/procedures.md：各阶段的完整代码（布料、Bifrost、MPM、缓存、VDB 审阅、精灵、USD、MASH）。编写脚本前加载。
• references/expert-notes.md：各位专家的原则及时间戳，以及专家意见不一致之处。需要了解某项设置的理由时加载。
• references/critique.md：评估模拟、缓存或散布效果的标准。判定效果完成前加载。
• references/gui-paths.md：供计算机操作 Agent 使用的菜单和快捷键，以及 Echo All Commands 的发现路径。
• references/sources.md：所有来源、凭据、URL 和最佳时间戳。
• scripts/mx_fx.py：工具包（docstring 列出了所有函数）。测试：tests/code/maya-fx/。