scenario-maya-modeling

Maya 建模（硬表面、有机体、道具）

专业建模讲究有目的的拓扑：每条循环边都服务于轮廓、高光、烘焙、UV 缝或关节；模型交付给下游时，不应留下需要下一个人清理的东西。Agent 由大到小逐步建模，用工具包衡量每个阶段，并在相信表面之前查看金属高光渲染。如果这里提到的同级技能不在你的可用技能中，请让用户安装（npx skills add scenario-labs/skills --skill <name>）；若处于无人值守状态，则根据工具架构继续操作并标明这一缺口。

必备背景： scenario-maya-expert（执行通道、审查循环、2027 版本陷阱）。 工具包：scripts/mx_modeling.py （sys.path[:0] = ["<skills>/scenario-maya-modeling/scripts", "<skills>/scenario-maya-expert/scripts"]; import mx_modeling as MM）， 配合 mx_audit、mx_validate、mx_review、mx_run 使用。**尚未在 Maya 中运行：**其纯 Python 层已通过离线测试；所有 Maya 调用仍待执行 tests/code/maya-modeling/run_all.sh。

立场（专家要点）

• 目的优先，然后才是密度。 CAD 或布尔运算生成的静帧可以跳过干净拓扑；游戏、动画和特写则不行（Mario Elementza [00:00:32]）。最低密度取决于最窄的特征，即“两条边之间的最短距离”[00:17:19]；之后由摄像机距离决定：低密度需要转向边并略微收紧（背景），高密度则无需这些处理（主角特写）[01:09:20] [01:39:46]。顶点数才是真正的成本：UV 缝、硬边和材质都会拆分顶点；位于 UV 缝上的硬边不增加成本（Polycount）。
• 先做好干净的未切割形体，再进行切割。 在平面上，先偏移再切割：偏移环会成为支撑循环边；在曲面部件上，则先切出支撑循环边，再添加细节（Mario [00:16:13] [00:38:16] [01:19:49]）。
• 网格均匀，绝不翻倍；循环边就是证明。 相邻四边面比例低于 2:1（Mario [00:08:31]）；循环边中断说明该区域尚未解决，循环边突然终止则意味着存在隐藏的双重挤出 [00:18:57] [00:39:22]。
• 三角面：移除、解决，再恢复；绝不使用 n 边形。 对于笼体，先移除三角面，解决其余部分，再只在通过金属测试的地方恢复一个；平面可以容忍，曲面和变形区域则不行（Mario [00:20:36] [00:29:59]；Jessica Dru Johnson [01:12:33]）。游戏低模中，三角面会让循环边局部终止（On Mars [00:10:29]）。清理只修复层叠面、非流形几何体和零长度几何体；n 边形需手动处理（FlippedNormals ToWRH4IXF7A [00:11:15] [00:11:50]）。
• 圆柱按四分之一划分，只用四边面封盖和环形循环边（Mario [00:57:43] [01:12:04] [01:14:16]； Pixar OpenSubdiv：不要使用高顶点数扇形）。
• **边缘支撑方法由目标用途决定，**细分只应在一个地方进行：Arnold 会在自身迭代的基础上渲染 Smooth Mesh Preview 的状态，因此每次保存时都要关闭预览（Arnold 细分文档；FlippedNormals [00:24:00]）。导出时会丢失折痕（antCGi RlNnp4qQIrU [00:28:12]）。
• 变形拓扑是建模师的职责。 每个关节使用一个控制循环边加两条支撑循环边（Jessica [01:15:51]）；隔离循环边用于限定控制范围 [01:14:11]；变形表面上不得有极点（antCGi QW8w15J00Ok [00:09:58]）；通过在设置完全相同的情况下弯曲两种拓扑，证明修复有效（antCGi x07USYlvu2o [00:16:24]）。
• 规范性是交付约定。 重建优于修补，名称应简短且唯一，渲染统计信息保持默认值；双面照明会掩盖翻转的面（FlippedNormals [00:08:31] [00:18:16] [00:02:35] [00:20:47]）。

首先确认

输入	变更	未说明时的默认值
目标	边缘支撑方法、三角化、法线	如果指定了引擎，则用于游戏（PC/主机）；否则用于离线 SubD
预算	精简多少	询问负责人；同时以 On Mars 的标准为依据（手榴弹级道具）：英雄道具在屏幕上占比较大时为 20k 到 30k 个三角面；次要或三级道具占屏幕 10 到 15% 时“少得多”（未给出具体数字）；背景道具为 10k 或 5k。报告三角面数和引擎顶点数，并说明保留每条边的理由
摄像机距离	保留的最窄特征、密度与重定向、转角柔和度	中景，玩家可以走到它旁边 [假设，已在报告中注明]
变形	每个关节的循环数、不使用加权法线、对称	道具：无；角色：是
尺寸、单位	倒角宽度、纹素计算	以厘米为单位的实际尺寸，放置于地面；即使引擎使用 Z 向上，Maya 场景也保持 Y 向上（FBX 导出或导入时会转换坐标轴）
枢轴	引擎中的放置方式	底部中心位于原点；如果关卡按角点对齐，则使用角点（Epic）
纹理集	堆叠、镜像、UV2	2048，使用唯一 UV（UV 属于 scenario-maya-retopology-uv）

工作流

每个阶段都是一个无界面的 mx_run 作业，关闭预览并保存新版本；GUI 桥接用于播放预览和交互式工具（替代方案见 references/procedures.md）。组件列表只能通过 MM.component_record 和 MM.carry_components 在各阶段间传递，绝不能通过名称传递，也不能使用拓扑 编辑前读取的索引（P18）。

1. 会话和简报。 cmds.about(version=True)（Smart Bevel 在 2027.1 和 2027.2 中发生了变化）， 单位为 cm，Y 轴朝上，简报以数字表示（P1）。关卡：写明假设。
2. 按实际尺寸制作粗模。 创建时为基本体命名，置于网格上，按规范设置枢轴，冻结变换，删除历史（P2）。关卡：mx_audit 显示已冻结，没有 default_name 或 duplicate_short_name，尺寸误差在 2% 以内［已添加］；将轮廓和灰模图表与参考图进行比较。
3. 主体形态，整洁的网格。 记录最窄特征（凹槽、凹壁、间隙）及其 宽度：附近的网格以该间距为准，其余部分与之协调；根据摄像机距离，决定每个角落的密度或 重定向方式。封闭最大的四边形，保持平衡，通过添加环线进行压力测试（Mario [00:10:11]）；使用 Edit Edge Flow 处理曲线（antCGi [00:16:04]）。关卡： 添加支撑环线前，MM.balance(m)["edges_over_limit"] == 0；MM.cage_report(m)：无 N 边面， 移除所有曲线三角面，或通过高光检查证明其合理；线框图表中环线连续。
4. 次要形态。 使用 MM.extrude(faces, offset_cm=...) 再进行凹入（P3；会拒绝空挤出）； 从单个四边形制作开口；使用 MM.cylinder_sides_for 和 MM.build_quad_cylinder 制作圆柱（P4），在开口处切割支撑环线；或在流形网格上使用 polyCBoolOp， 然后应用 Smart Bevel（P5）。关卡：零长度边、重合边对和非流形元素均为 0。
5. 根据目标用途控制边缘：
   • 用于 SubD 主体或高模烘焙、需要跨软件兼容：使用支撑环线（偏移环、倒角立方体角落布线， Mario [00:44:24]）。
   • 用于留在 Maya、Arnold 或 USD 中的 SubD：使用折痕，只用一种方法，数值不超过渲染级别 （MM.crease、MM.crease_report、P6）。
   • 游戏低模：使用 MM.bevel 倒角（布尔运算后用 Smart Bevel，干净四边形上用旧版 Fractional）， 再加上 MM.weighted_normals；或者在 UV 缝上设硬边，并烘焙法线贴图 （Polycount）。
   • 仅从 CAD 或布尔运算生成的模型：使用 Smart Bevel，不做重拓扑。关卡： MM.cage_report(cage)["ready_to_smooth"]（硬边为 0，因为分面块也算硬边， Mario [01:28:38]；无扇形封顶；6 个及以上极点均有合理依据）；MM.highlight_review(..., subdiv=n) 检查所有切口上的条纹是否连续；bevel 的 problems 为空；crease_report 无问题。
6. 游戏低模和烘焙准备（P10）。对高模执行 MM.smooth_copy；复制笼型网格，只通过删除边来生成低模 （在轮廓外使用 MM.flat_edges，并以三角面终止环线）；在圆角处使用半径边，均匀分布，在凸脊上放置一条 （On Mars [00:12:50] [00:26:34]）；与主体接触的部件要焊接到主体上，或删除其隐藏面 （Polycount：低模保持连通）； 使用 MM.shrink_wrap；使用 MM.set_hard_by_angle(low, 45)；使用 MM.triangulated_copy(low, toward=high) 生成用于烘焙和导出的版本。关卡：记录 MM.deviation，轮廓重合，三角面数在预算内，报告引擎顶点数，每个独立壳体（polyEvaluate(shell=True)）均有合理依据， diagonals_wrong_after == 0。
7. 角色：变形检查（P13）。手腕和脚踝处布线，眼睑和嘴唇的环线数量一致，脸颊下方有嘴角环线， 面部处于中性状态（antCGi；Jessica [01:00:30]）。关卡：MM.bend_test 显示无翻转，且相较上一版拓扑没有退化；restored 为 true。
8. 清理和交接（P14、P15）。运行 MM.cleanup_technical、MM.inverted_shells、 MM.handoff_report(roots, out, to=...)、 mx_validate.validate(profile="model", fix=SAFE_FIXES + ("render_stats",))，再次生成报告，并保存 新版本。关卡：报告显示 ok；清理显示 ok；反转壳体数为 0；预览已关闭；待办事项已命名；图表已打开。

数值

数值	设置	相对于 / 来源
邻接四边面尺寸	小于 2:1	基础网格，不含支撑循环（Mario [00:08:31]）
最小密度	间距 = 最窄特征	其余部分以此为基准调整（Mario [00:17:19]）
圆柱侧数	20、24、28、32	4 的倍数，与切口对齐（Mario [01:12:04]）
笼子上的圆形特征	主体约 6 跨，背景 4 跨	OpenSubdiv
顶点度	4 为规则；6+ 为警示；GPU 上限约为 27	OpenSubdiv
可见圆角上的半径边线	多于 2 到 3 条，间距均匀，其中一条位于顶峰	On Mars [00:25:29] [00:26:34]
每个关节的循环	1 条控制循环 + 2 条支撑循环；指关节为 3 条	Jessica [01:15:51] [01:17:34]
折痕	Maya 值 N 表示 N 个折痕级别；通常很少超过 5；10 会在置换下撕裂	Maya Help；OpenSubdiv
Smart Bevel	宽度使用世界单位；深度 1 为倒角，0.5 为圆角；1 个分段较硬，2 到 3 个分段较常见	Maya 2027 Help
旧版倒角默认值	分数模式、1 个分段、深度 1、平滑角度 30；盒角使用 2 个分段	Maya 2027 Help；FlippedNormals [00:18:18]
机械低模上的硬边	大于约 45 度，以及位于 UV 缝处	Polycount
手榴弹预算	笼子 61k，低模 24k；“polygons”约为三角形数的一半	On Mars [00:04:21] [00:21:31]
贴图占比	表面 cm² x (px/cm)² / 贴图 px²（10.24 时，12,800 cm² 占 2048² 的 32%）	算术计算 [新增]
细分成本	每级多出 x4 个多边形；预览级别 + Arnold 迭代次数会累加	Arnold doc

质量关卡

可测量，按网格检查： mx_audit.verdict(mx_audit.audit(m, texture_size=2048), "game" | "film" | "subd", max_tris=budget) 不包含 error，且通过每个 GATE 中列出的 MM 检查；场景： mx_validate.validate(profile="model") 不包含 fail；两者合并：MM.handoff_report。视觉检查，每次都要打开： mx_review.review 检查表（与参考图对比轮廓、粘土视图、线框循环、法线）； MM.highlight_review 使用 focus= 查看每处切口的特写（折痕、暗色条纹、波动都属于夹捏，Mario 帧 00:12:45、01:38:42）；高模与低模轮廓并排对照；在 GUI 会话中， 关闭双面照明或启用背面剔除。使用 references/critique.md 进行评估。

常见错误

错误	表现	修复
空挤出	循环直接停止；平滑预览中出现折痕	MM.extrude 会拒绝此操作；使用 mx_audit 检查零长度边
圆柱体上的垂直切线	高光摇摆不定	增加边数后重建，或平滑一次
扇形封盖	封盖中心出现凹痕	cage_report 检查扇形极点；使用 MM.build_quad_cylinder
笼体上残留硬边	平滑后出现分面区域	执行 polySoftEdge(angle=180)，直到 cage_report 显示硬边为 0
启用细分进行清理	出现随机三角剖分	使用 MM.cleanup_technical；手动处理 n-gon
保存时开启预览，同时 Arnold 迭代次数过多	文件臃肿，渲染速度极慢	在同一处设置 MM.subdiv_setup；使用 mx_validate 检查 smooth_preview
FBX 资源上带有折痕	在引擎中锐度消失	倒角，或附带一份平滑后的副本
变形网格上使用加权法线	蒙皮时着色效果固定不变	仅用于静态网格
UV 缝处的硬边关闭	顶点数增加，却没有收益	在硬边处设置缝线（hard_edge_components）
整个外壳内外翻转	关闭双面照明时显示为黑色，开启时正常	使用 MM.inverted_shells 检查并反转
使用 V 吸附但未焊接	平滑预览中出现接缝	使用 Target Weld；检查 coincident_vertices
高处圆角、低处保持尖锐	烘焙瑕疵	为低处边缘添加圆角，顶部保留一条边
低模悬空，或部件相交	烘焙遗漏、重叠错误、隐藏面占用 UV 空间	使用 MM.shrink_wrap；焊接部件，或删除隐藏面
引擎选择对角线	出现脊线而非谷线，着色呈锯齿状	使用 MM.triangulated_copy(toward=high)，导出三角剖分结果
编辑后重复使用组件 ID	删除了错误的边，轮廓丢失	MM.carry_components 会拒绝；重新推导
肢体环线呈螺旋状，极点位于胸部	权重混乱，出现扭结	使用同心环线，重新布置极点

交接

• 从 scenario-maya-expert 接收简报；从 scenario-zbrush-expert 接收雕刻模型（检查比例；ZBrush 没有单位；方向；锁定的法线）；从 scenario-3d 接收生成的网格（仅作为参考或用于烘焙高模）。
• 交付给 scenario-maya-retopology-uv（UV、烘焙准备）：新版本 <asset>_model_v###.ma、包含 _geo 网格的 <asset>_GRP（游戏引擎名称，例如 SM_ 和 UCX_）、笼体、<asset>_high（浮雕单独放置，并为 AO 关闭 castsShadows）（Polycount）、已构建的低模、待处理 UV 的 handoff_<to>.json、用于 UV 切割的硬边列表，以及查看过的参考图表。三角化后也必须保持流形：Unfold3D 会拒绝非流形网格，并展开三角化副本（P17）。
• 交付给 scenario-maya-rigging（变形就绪）：to="rigging" 清理完成（X 轴对称、没有锁定法线、没有历史记录）、贴地并居中、眼睛分离且朝前、对称部件已合并、bend_test 数值（antCGi e74K 检查清单）。
• 交付给 scenario-maya-lookdev（电影级 SubD）：细分设置集中在一处，折痕集命名并带有数值，预览关闭。FBX 导出交给 scenario-maya-pipeline-scripting。

Maya 2027 说明

• Smart Bevel（polySmartBevel，2027）：Width 使用世界单位，Depth profile，Filter 默认值为 Selected Edges；2027.0、.1、.2 的输出各不相同；探测前标志未知（MM.bevel 会记录 attr_map）。其盒角行为尚未测试：2 段规则源自旧版倒角，因此请查看 problems 调查结果。旧版倒角称为“legacy bevel”，自 2025 起，其布尔运算支持 Filter 属性和仅处理交线的倒角。
• Shift+拖动是“Shift Extrude”（2025）；Smart Extrude 会缝合重叠面，Edit Mesh > Extrude 则不会。布尔运算：polyBoolean（2023）、3ds Max 引擎（2025.3）、Volume 模式（2026）。
• Smooth Mesh Preview 使用 OpenSubdiv Catmull-Clark；Crease Tool 和 Crease Sets 按组件互斥。
• 新场景默认使用 OpenPBR Surface；高光检查使用 aiStandardSurface。
• Reduce 是减面，不是重新拓扑；Quad Draw 仅支持交互操作。
• FBX 导入可带入用户法线（2027）；导入的法线可能处于锁定状态（Mesh Display > Unlock Normals）。
• macOS 按键：Ctrl 对应 Control，Alt 对应 Option。

参考资料

• references/procedures.md：P1 至 P18 的完整代码及测试路径。编写任何建模代码前请加载。
• references/critique.md：评审标准。每个检查点及报告前都要加载。
• references/expert-notes.md：每位专家的推理、时间戳和分歧。遇到不熟悉的资产类型或需要作出判断时加载。
• references/gui-paths.md：GUI 或计算机操作会话的菜单和快捷键。
• references/sources.md：来源、凭据和最佳时间戳。