scenario-maya-rigging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maya rigging

Maya 绑定

Expert rigging means every value is explained and every behavior measured: joints at real pivots with computed orientation, controls at zero with their placement in offsetParentMatrix, IK/FK and space switches that move nothing, and a rig that survives scale, distance, several characters per shot and an animator keying everything. The rig is the output of a build script and data. If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add scenario-labs/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-maya-expert (execution channel, review loop, 2027 version traps).

Module

scripts/mx_rig.py

(

sys.path.insert(0, "<skills>/scenario-maya-rigging/scripts"); import mx_rig as R

): not yet run in Maya; its pure math passed offline (

test_rig_offline.py

). With Maya installed, run

tests/code/maya-rigging/run_all.sh

and fix what

test_rig_probe

contradicts.

专业绑定意味着每个数值都有明确依据，每项行为都经过测量：关节位于真实枢轴位置并通过计算定向；控制器保持零位，其放置变换存储在 offsetParentMatrix 中；IK/FK 和 space switch 切换时不会产生位移；绑定能够承受缩放、远距离、同一镜头中的多个角色，以及动画师对所有属性打关键帧。绑定是构建脚本与数据的产物。如果当前可用 skill 中缺少此处提及的某个同级 skill，请让用户安装（

npx skills add scenario-labs/skills --skill <name>

）；在无人值守场景中，则依据工具 schema 继续执行并标记该缺口。

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

模块

scripts/mx_rig.py

（

sys.path.insert(0, "<skills>/scenario-maya-rigging/scripts"); import mx_rig as R

）：尚未在 Maya 中运行；其纯数学逻辑已通过离线测试（

test_rig_offline.py

）。安装 Maya 后，运行

tests/code/maya-rigging/run_all.sh

，并修复

test_rig_probe

揭示的不一致之处。

Stance (the expert delta)

立场（专家能力增量）

Clean values, one place for each. Rotations zero at rest, orientation in jointOrient (or nowhere: Fragapane), control placement in offsetParentMatrix (antCGi; Maya Learning Channel). OPM composes,
```
world = local * OPM * dagParentWorld
```
(2027 transform node): feed
```
.matrix
```
for a relative drive, or multiply a
```
worldMatrix
```
by the DAG parent's
```
worldInverseMatrix
```
, then zero translate, rotate and jointOrient or they apply twice (Maya Learning Channel; antCGi's leg rotating backwards).
Compute, never eyeball.
```
-orientJoint
```
silently skips joints with rotations or no child (2027 cmds.joint); a secondary world axis along the bone is ill-defined (antCGi's toes).
```
R.joint_chain
```
computes jointOrient from positions; a pole on the chain plane adds zero drift (
```
R.pole_vector_position
```
) [added].
The animator defines done. Zero pop switching IK/FK at neutral, only the active mode visible, everything else locked because animators "select hierarchy and key all", limits at breaking points, behavior mirroring on limbs, same orientation on eyes and face (antCGi).
Matrices before constraint stacks, and know the blend. OPM, blendMatrix and pickMatrix keep channels free (Maya Learning Channel cut 20 joints from one hand). blendMatrix is an ordered stack, each target overriding the ones before (equal thirds: 1, 1/2, 1/3); parentMatrix (2025) normalizes and stores per-target offsets (2027 Help). Spaces blend offset targets, never the space itself, or the IK flips (antCGi).
The built rig is disposable. Guides, build script, serialized weights and settings; fixes go back into the data (Miquel Campos, mGear: "we serialize everything and we build clean every single time"; Bungie). Metadata and joint labels, not names, identify chains (Bungie). A skinCluster reads only influence world matrices and bindPreMatrix: reset the bind pose, never rebuild joints for it (Fragapane).
Structure decides speed. The Evaluation Graph leaves static curves out and rebuilds at the first differing key; without curves a rig "is going to be paralyzed terribly" (Fragapane; Using Parallel Maya 2027). Split components so cheap global work finishes early, even by duplicating cheap math (Fragapane); no Python nodes, scene-querying expressions or driven
```
frozen
```
; hosts out of the limbs (Miquel Campos); DG, Serial and Parallel agree before optimizing.
Test at the extremes. Scale 1.24 and 1.6 (antCGi), a million units away and upside down (Fragapane), three referenced characters, a quick bind while building (antCGi).
Deformation skeleton apart from the control rig. Engines see joints, skin and blendshapes only: one root at the origin, engine names, a joint budget (antCGi, Unreal and Unity docs, Bungie).

数值干净，每个值只有一个归属。 静止姿态下旋转为零，方向存储在 jointOrient 中（或完全不设置：Fragapane），控制器放置存储在 offsetParentMatrix 中（antCGi；Maya Learning Channel）。OPM 会进行组合，
```
world = local * OPM * dagParentWorld
```
（2027 transform node）：对于相对驱动，传入
```
.matrix
```
；或者将
```
worldMatrix
```
乘以 DAG 父节点的
```
worldInverseMatrix
```
，然后将 translate、rotate 和 jointOrient 归零，否则它们会被应用两次（Maya Learning Channel；antCGi 的腿部反向旋转问题）。
进行计算，绝不凭目测。
```
-orientJoint
```
会静默跳过带旋转或没有子节点的关节（2027 cmds.joint）；沿骨骼方向设置次世界轴会产生未定义结果（antCGi 的脚趾问题）。
```
R.joint_chain
```
根据位置计算 jointOrient；位于链平面上的 pole 不会产生漂移（
```
R.pole_vector_position
```
）[新增]。
由动画师定义完成标准。 在中性姿态切换 IK/FK 时不得跳变，只显示当前活动模式；其余内容全部锁定，因为动画师会“选择层级并对全部内容打关键帧”；在弯折点设置 limits；肢体行为保持镜像；眼睛和面部的朝向一致（antCGi）。
先处理矩阵，再处理约束堆栈，并理解混合方式。 OPM、blendMatrix 和 pickMatrix 可让通道保持可用（Maya Learning Channel 通过一个手部减少了 20 个关节）。blendMatrix 是有序堆叠，每个目标都会覆盖之前的目标（均分为三份时：1、1/2、1/3）；parentMatrix（2025）会归一化并存储各目标的偏移（2027 Help）。space 应对偏移目标进行混合，而不能混合 space 本身，否则 IK 会翻转（antCGi）。
构建出的绑定是可重新生成的。 指南、构建脚本、序列化权重和设置才是源数据；修复应回写到数据中（Miquel Campos、mGear：“我们序列化所有内容，并且每次都从头干净地构建”；Bungie）。链应通过元数据和关节标签识别，而不是名称（Bungie）。skinCluster 只读取影响项的世界矩阵和 bindPreMatrix：重置绑定姿势，不要为此重建关节（Fragapane）。
结构决定速度。 Evaluation Graph 会排除静态曲线，并在第一个不同的关键帧处重建；没有曲线时，绑定“会严重陷入瘫痪”（Fragapane；Using Parallel Maya 2027）。拆分组件，让开销较低全局的计算尽早完成，即使这意味着重复执行廉价计算（Fragapane）；不要使用 Python 节点、查询场景的表达式或被驱动的
```
frozen
```
属性；host 应置于肢体之外（Miquel Campos）；优化前应确认 DG、Serial 和 Parallel 的结果一致。
在极端条件下测试。 缩放 1.24 和 1.6（antCGi），距离一百万单位且上下颠倒（Fragapane），三个引用角色，以及构建过程中快速绑定（antCGi）。
将变形骨架与控制器绑定分离。 引擎只会看到关节、skin 和 blendshape：原点处只有一个根节点，使用引擎名称，并遵守关节预算（antCGi、Unreal 和 Unity 文档、Bungie）。

Establish first

首先确定

Input	Changes	Default when silent ([added] unless attributed)
Target	film keyframe rig vs engine skeleton (names, axes, influences, one root)	feature keyframe rig, custom
Camera distance, style	auto-rigger or custom; twist and corrective joints; stylized: crude proportion rig and art-direction paintovers first, final-aim notes from day one (Miquel Campos)	hero: custom; crowd: Quick Rig
Skeleton convention	reusing engine animation needs its names and hierarchy	X down the bone, bend on local Z, positive Z flexes
Animator conventions	IK/FK default, spaces, colors, pickers	arms FK, legs IK; spaces world, cog, chest, head; ask
Shot load	characters per shot, dense meshes	three referenced characters
Face, mocap, budget	face to scenario-maya-deformation; HumanIK; joint and influence counts	jaw, eyes, aim control; ask the lead (antCGi: "it pays to be frugal")

输入	变更	未提供信息时的默认值（除另有注明外均为[新增]）
目标	影视关键帧绑定或引擎骨架（名称、轴、影响项、单一根节点）	功能性关键帧绑定，自定义
镜头距离、风格	自动绑定工具或自定义；扭转关节和纠正关节；风格化角色先制作粗略比例绑定和美术指导性绘制修正，并从第一天起记录最终瞄准说明（Miquel Campos）	主角：自定义；群演：Quick Rig
骨架约定	复用引擎动画时，需要采用其名称和层级	骨骼沿 X 轴向下，在局部 Z 轴弯曲，正 Z 方向产生弯曲
动画师约定	IK/FK 默认设置、spaces、颜色、选择器	手臂使用 FK，腿部使用 IK；spaces 为 world、cog、chest、head；询问用户
镜头负载	每镜头角色数量、密集网格	三个引用角色
面部、mocap、预算	面部交给 scenario-maya-deformation；HumanIK；关节和影响项数量	下颌、眼睛、aim 控制器；询问负责人（antCGi：“精打细算很重要”）

Choose the path

选择路径

Quick Rig + HumanIK	AdvancedSkeleton	mGear Shifter	Custom ( `mx_rig` )
biped facing +Z; game or background character "not looked at closely" (Maya Learning Channel); HumanIK when animation is retargeted (2027 Help); 15 nodes, strict T-stance	body plus face from a fit skeleton, rebuilt by toggling fit; engine export via Convert to BlendShapes Only	many characters, a team, Unreal exporter; confirm a 2027 build for the OS first [verify]	hero rig, strict engine skeleton, rigs the agent must rebuild and verify: this workflow

Quick Rig + HumanIK	AdvancedSkeleton	mGear Shifter	自定义（ `mx_rig` ）
双足角色朝向 +Z；游戏或背景角色“不会被仔细观看”（Maya Learning Channel）；需要重定向动画时使用 HumanIK（2027 Help）；15 个节点，严格采用 T-pose	基于 fit skeleton 生成身体和面部，通过切换 fit 重新构建；使用 Convert to BlendShapes Only 导出到引擎	适用于大量角色、团队协作和 Unreal exporter；先确认目标 OS 存在 2027 build [待验证]	主角绑定、严格的引擎骨架，以及 Agent 必须重新构建和验证的绑定：采用此工作流

Workflow

工作流

Gate the model.
```
mx_validate.validate(profile="model")
```
clean; cm; height to spec (about 180); feet at y = 0; centered on X; frozen; eyes dead ahead; loops at knuckles, elbows, knees; mouth bag for a face (antCGi). Send problems back as a list; never edit a client model unasked. GATE: no fail; wire sheet looked at.
Place joints at pivots on edge loops: spine joint under the rib cage (antCGi), wrist decoupled from the palm (Fragapane), elbows pre-bent back, knees forward; the first upper-arm and thigh twist joint stays at the top with the shoulder or hip, mid twist joints are placed by position so they keep the parent's orientation (antCGi). GATE:
```
R.chain_plane
```
does not raise on any limb; joints over wireframe looked at.
Build and orient.
```
R.joint_chain(spec, parent, up="plane")
```
for limbs,
```
up=(0, 0, 1), up_axis="y"
```
for spine and neck,
```
world=[...]
```
for root, cog, head, eyes and feet (antCGi: animators, engine foot placement),
```
end_aim=
```
for clavicles; existing skeletons:
```
R.orient_with_cmds
```
('zup' for legs and spine).
```
R.mirror_chain
```
: behavior for limbs, orientation for eyes and face; rotate orders on controls (
```
R.rotate_order(twist, main)
```
; Fragapane);
```
R.set_preferred_angles(root)
```
. GATE:
```
R.rig_check(joints=bind)
```
clean; mirror within 1e-3 cm; all digits curl on one axis and sign, thumb fixed, so one attribute makes a fist (antCGi).
Hand the bind skeleton to scenario-maya-deformation (it binds while you build controls): joints only, one hierarchy, labels,
```
rig_check
```
JSON.
Control rig.
```
R.ikfk_limb(bind[:3], name, rig_parent, ctrl_parent, own_solver=char + "_ikRPsolver")
```
: handles of a type share one solver node, so several characters in a scene conflict (Fragapane: "can make a mess"; 2027 Help). Legs:
```
extra=[ball, toe], orient_end=False
```
, then
```
R.reverse_foot
```
with
```
R.foot_pivots_from_mesh
```
; spine P9;
```
R.space_switch(ctrl, [None, cog, chest], names=[...])
```
;
```
R.ikfk_match(meta, to="fk"|"ik", key=True)
```
uses stored offsets (antCGi instead adds a pole locator under the FK elbow and an ankle locator oriented like the IK foot). GATE:
```
R.neutral_switch_test
```
and pole drift below 1e-3;
```
R.space_test
```
as expected; FK and IK posed apart,
```
R.blend_sweep_test
```
finds no flip; roll sweep plants heel, ball, toe in turn; no shared-solver error; controls at zero.
Scale and stretch. Root scale only on groups that do not inherit it; stretch base lengths times root scaleY; IK spine joints under a world-pivot scale group, as segmentScaleCompensate blocks scale (antCGi). GATE:
```
R.scale_test
```
at 1.24 and 1.6, neutral and stretched, below 1e-3 cm.
Lock down.
```
R.lockdown
```
; FK hinges keep their bend axis; limits; controller tags; selection sets. GATE:
```
R.lockdown_audit
```
and
```
R.opm_audit(rig)
```
empty; the rig still works.
Performance. Key first (
```
R.rom_keys
```
, two different values per used attribute): a keyless rig profiles fast and lies.
```
R.eval_census(rig)
```
,
```
R.eval_ab(bind, meshes, frames)
```
;
```
R.prepare_eval_graph(root=rig)
```
tags every control (with the animator's Preferences > Settings > Animation > Include controllers in evaluation graph, first keys stop rebuilding the graph) and turns on the curve manager for the session.
```
R.gpu_override_census(meshes)
```
, then the GUI Evaluation HUD must show a non-zero k count, else
```
deformerEvaluator -meshes
```
says why. Profile DG, Serial, Parallel and GPU Override with 1 and 3 referenced characters; keep dated profiles (Miquel Campos). GATE: no census error; modes agree within 1e-5; each dense mesh on the GPU or its reason written.
Review.
```
R.rom_keys
```
, then
```
mx_review.playblast
```
(GUI) or
```
R.pose_review
```
(headless);
```
R.precision_test
```
at shot distances;
```
references/critique.md
```
. GATE: frames looked at; elbows, knees, shoulders, wrists, feet read right.
Deliver. New version,
```
validate(profile="rig")
```
clean, test JSON, playblast, what was not verified.

对模型执行门禁。
```
mx_validate.validate(profile="model")
```
通过；单位为 cm；高度符合规格（约 180 cm）；脚位于 y = 0；在 X 轴上居中；已冻结；眼睛正向前方；指关节、肘部和膝部具有边环；面部具有 mouth bag（antCGi）。将问题以列表形式退回；未经允许绝不修改客户模型。GATE：不得失败；已对照线框检查。
放置关节。 在边环的枢轴位置放置关节：脊柱关节位于胸廓下方（antCGi），腕关节与手掌解耦（Fragapane），肘部预先向后弯曲，膝盖向前；上臂和大腿的第一个扭转关节与肩或髋一起保留在顶部，中段扭转关节根据位置放置，从而保持父关节的方向（antCGi）。GATE：
```
R.chain_plane
```
在任何肢体上都不得报错；已对照线框检查关节位置。
构建并定向。 肢体使用
```
R.joint_chain(spec, parent, up="plane")
```
，脊柱和颈部使用
```
up=(0, 0, 1), up_axis="y"
```
，根节点、cog、头、眼睛和脚使用
```
world=[...]
```
（antCGi：动画师、引擎脚部放置），锁骨使用
```
end_aim=
```
；对于已有骨架，使用
```
R.orient_with_cmds
```
（腿和脊柱使用 'zup'）。
```
R.mirror_chain
```
：肢体镜像行为，眼睛和面部镜像方向；设置控制器的旋转顺序（
```
R.rotate_order(twist, main)
```
；Fragapane）；
```
R.set_preferred_angles(root)
```
。GATE：
```
R.rig_check(joints=bind)
```
通过；镜像误差在 1e-3 cm 内；所有手指沿同一轴和同一方向弯曲，拇指固定，从而只需一个属性即可握拳（antCGi）。
将绑定骨架交给 scenario-maya-deformation（它会在你构建控制器时执行蒙皮）：只包含关节、单一层级、标签和
```
rig_check
```
JSON。
构建控制器绑定。
```
R.ikfk_limb(bind[:3], name, rig_parent, ctrl_parent, own_solver=char + "_ikRPsolver")
```
：同类型 handle 会共享一个 solver 节点，因此场景中的多个角色会相互冲突（Fragapane：“可能一团糟”；2027 Help）。腿部：
```
extra=[ball, toe], orient_end=False
```
，随后使用
```
R.reverse_foot
```
和
```
R.foot_pivots_from_mesh
```
；脊柱使用 P9；
```
R.space_switch(ctrl, [None, cog, chest], names=[...])
```
；
```
R.ikfk_match(meta, to="fk"|"ik", key=True)
```
使用存储的偏移（antCGi 则是在 FK 肘部下方添加 pole locator，并添加一个方向与 IK 脚部一致的 ankle locator）。GATE：
```
R.neutral_switch_test
```
通过且 pole 漂移低于 1e-3；
```
R.space_test
```
符合预期；将 FK 和 IK 摆到不同姿势，
```
R.blend_sweep_test
```
未发现翻转；roll sweep 依次使脚跟、脚掌和脚趾正确落地；不存在共享 solver 错误；控制器保持零位。
缩放与拉伸。 根缩放仅施加到不继承该缩放的组；拉伸基础长度乘以根节点的 scaleY；IK 脊柱关节置于世界枢轴缩放组下，因为 segmentScaleCompensate 会阻止缩放（antCGi）。GATE：在 1.24 和 1.6 倍缩放、中性姿态及拉伸姿态下，
```
R.scale_test
```
的误差低于 1e-3 cm。
锁定。 执行
```
R.lockdown
```
；FK 铰链保留其弯曲轴；设置 limits；添加控制器标签和选择集。GATE：
```
R.lockdown_audit
```
和
```
R.opm_audit(rig)
```
均无问题；绑定仍可正常使用。
性能。 先打关键帧（
```
R.rom_keys
```
，每个已使用属性设置两个不同值）：无关键帧的绑定在性能分析时速度很快，但结果具有欺骗性。执行
```
R.eval_census(rig)
```
、
```
R.eval_ab(bind, meshes, frames)
```
；
```
R.prepare_eval_graph(root=rig)
```
会标记所有控制器（同时需在动画师的 Preferences > Settings > Animation > Include controllers in evaluation graph 中启用该选项，首个关键帧会停止重建该图），并为当前会话启用 curve manager。执行
```
R.gpu_override_census(meshes)
```
，随后 GUI Evaluation HUD 必须显示非零的 k 计数，否则
```
deformerEvaluator -meshes
```
会说明原因。分别使用 1 个和 3 个引用角色，对 DG、Serial、Parallel 和 GPU Override 进行性能分析；保留带日期的性能报告（Miquel Campos）。GATE：census 无错误；各模式结果在 1e-5 范围内一致；每个密集网格均运行于 GPU，或已记录无法运行的原因。
审查。 执行
```
R.rom_keys
```
，随后运行
```
mx_review.playblast
```
（GUI）或
```
R.pose_review
```
（无头模式）；在实际镜头距离下执行
```
R.precision_test
```
；参阅
```
references/critique.md
```
。GATE：已逐帧查看；肘、膝、肩、腕和脚的姿态正确。
交付。 提供新版本、干净的
```
validate(profile="rig")
```
、测试 JSON、playblast，以及尚未验证的事项。

Numbers

数值

Value	Relative to	Source
Twist joints: upper arm 2 (top, mid), lower arm 1, thigh 2, calf 1, plus wrist and foot	bone	antCGi
Pole locator 30 units out by hand; computed pole distance = longer segment	elbow	antCGi; [added]
Switch, drift, scale error below 1e-3 cm; mid-blend path within max(1 deg, 5%) of the direct angle	bind joints	[added] gates
Foot break 25 deg: ball = roll to 25, then 50 - roll; toe = roll - 25; limits footRoll -40..80, footBank -60..60	footRoll	antCGi
Mid spine twist falloff 1, 0.5, 0.25	ribbon joints	antCGi
Precision: problems at 1e5 units, flicker at 1e6	rig top node	Fragapane
Hosts out of limbs: 20 to 17 ms per frame	one character	Miquel Campos
GPU Override: over 2000 vertices (NVIDIA), 500 (AMD); `MAYA_OPENCL_DEFORMER_MIN_VERTS` , 0 sends all	per mesh	Using Parallel Maya 2027
blendMatrix equal shares: 1, 1/2, 1/3 ...; counting the inputMatrix: 1/2, 1/3 ...	ordered stack	2027 Help; [added]
HumanIK 15 nodes; Unity 4 influences; Unreal FBX 2020.2	engine contract	docs

数值	相对于	来源
扭转关节：上臂 2 个（上端、中段），前臂 1 个，大腿 2 个，小腿 1 个，另加腕部和脚部	骨骼	antCGi
pole locator 手动设置在向外 30 个单位处；计算出的 pole 距离等于较长的一段	肘部	antCGi；[新增]
切换、漂移和缩放误差低于 1e-3 cm；混合中点路径与直接角度的偏差不超过 max(1 deg, 5%)	绑定关节	[新增]门禁
脚部弯折 25 deg：ball = roll 到 25，然后为 50 - roll；toe = roll - 25；limits 为 footRoll -40..80、footBank -60..60	footRoll	antCGi
脊柱中部扭转衰减为 1、0.5、0.25	沿脊柱分布的关节	antCGi
精度：在 1e5 单位处出现问题，在 1e6 单位处出现闪烁	绑定顶层节点	Fragapane
将 host 置于肢体之外：每帧从 20 毫秒降至 17 毫秒	单个角色	Miquel Campos
GPU Override：超过 2000 个顶点（NVIDIA）或 500 个顶点（AMD）； `MAYA_OPENCL_DEFORMER_MIN_VERTS` ，设为 0 可发送全部网格	单个网格	Using Parallel Maya 2027
blendMatrix 等分权重：1、1/2、1/3……；计算 inputMatrix 时：1/2、1/3……	有序堆叠	2027 Help；[新增]
HumanIK 15 个节点；Unity 4 个影响项；Unreal FBX 2020.2	引擎约定	文档

Quality gates

质量门禁

Code (

mx_rig

rig_check

(rest rotations, orientation, controls, poles, shared solvers, OPM doubling, evaluation census, lockdown),

neutral_switch_test

blend_sweep_test

space_test

scale_test

precision_test

eval_ab

gpu_override_census

game_skeleton_check

; scenario-maya-expert's

validate(profile="rig")

Visual: placement over wireframe front and side; ROM playblast of every control axis, front, side and three-quarter; foot roll scrubbed; scaled rig in an extreme pose. Look for knee pop, elbow flips, candy-wrapper wrists, collapsing shoulders, sliding feet.

代码（

mx_rig

）：

rig_check

（静止旋转、方向、控制器、pole、共享 solver、OPM 重复应用、evaluation census、lockdown）、

neutral_switch_test

、

blend_sweep_test

、

space_test

、

scale_test

、

precision_test

、

eval_ab

、

gpu_override_census

、

game_skeleton_check

；以及 scenario-maya-expert 的

validate(profile="rig")

。

视觉：对照正面和侧面线框检查放置；对每个控制器轴制作正面、侧面和四分之三视角的 ROM playblast；拖动检查 foot roll；在极端姿势下检查缩放后的绑定。留意膝盖跳变、肘部翻转、腕部像糖纸一样扭转、肩部塌陷和脚部滑动。

Common mistakes

常见错误

Mistake	What it looks like	Fix
Orient Joint on a joint with rotations	nothing changes, no error	freeze rotations first, or `R.joint_chain`
Secondary world axis along the bone ('yup' on a leg, world Z on forward toes)	thigh and calf axes disagree	an axis across the bone; `R.orient_with_cmds` refuses it
Straight elbow or knee	IK bends the wrong way or backwards	pre-bend, rebuild, set preferred angle
Pole off the chain plane; pole too close	elbow drifts when constrained; arm flips as the hand moves	`R.pole_vector_position` ; move it farther behind
worldMatrix into OPM under a moving parent, or values left under an OPM drive	double transform, reversed rotation	parent's worldInverseMatrix or `.matrix` ; `R.bake_to_opm` ; `R.opm_audit`
Equal blendMatrix weights for an average	the last target wins	1, 1/2, 1/3, or a parentMatrix node
Blending to a space's own matrix	control snaps onto the target, IK flips	offset targets ( `R.space_switch` )
Handles on the scene's shared solver	referenced characters conflict; one edit changes every rig	`own_solver` per character
Settings host inside the limb	slow playback (node-level cycle)	host on the limb's parent space
Flip mid IK/FK blend	toes or wrist spin halfway	constraint blend: interpType Shortest (antCGi); matrix blend: measure with `R.blend_sweep_test`
Profiling a keyless rig	numbers collapse once animated; stutter on first keys	keys first; controller tags plus prepopulation
GPU Override HUD "Enabled (0 k)"	nothing deforms on the GPU	`R.gpu_override_census` , `deformerEvaluator -meshes`
Scale wired twice, or stretch not normalized	double scaling; limbs stretch when the rig scales	scale non-inheriting groups only; base length times root scaleY
Groups, handles, locators unlocked	"key all" breaks the rig	`R.lockdown`
Spline curve under its start joint; helpers under bind joints	dependency cycle; engine export errors	keep both outside the bind skeleton

错误	表现	修复方式
对带旋转的关节执行 Orient Joint	没有任何变化，也不会报错	先冻结旋转，或使用 `R.joint_chain`
次世界轴与骨骼方向重合（腿上的 'yup'，前向脚趾上的 world Z）	大腿与小腿的轴不一致	使用横跨骨骼的轴； `R.orient_with_cmds` 会拒绝这种情况
肘部或膝盖保持笔直	IK 向错误方向或向后弯曲	预弯曲、重新构建并设置 preferred angle
pole 偏离链平面或距离过近	受到约束时肘部漂移；手部移动时手臂翻转	`R.pole_vector_position` ；将其进一步移至后方
在移动父节点下将 worldMatrix 写入 OPM，或在 OPM 驱动下仍保留通道值	重复变换、旋转反向	使用父节点的 worldInverseMatrix 或 `.matrix` ； `R.bake_to_opm` ； `R.opm_audit`
为求平均而使用相等的 blendMatrix 权重	最后一个目标获胜	使用 1、1/2、1/3，或使用 parentMatrix 节点
混合到 space 自身的矩阵	控制器吸附到目标，IK 翻转	使用偏移目标（ `R.space_switch` ）
Handle 使用场景中的共享 solver	引用角色相互冲突；一次编辑影响所有绑定	每个角色使用独立的 `own_solver`
Settings host 位于肢体内部	播放速度缓慢（节点级循环）	将 host 放在肢体的父级空间中
IK/FK 混合过程中发生翻转	脚趾或手腕在混合中途旋转	约束混合：interpType Shortest（antCGi）；矩阵混合：使用 `R.blend_sweep_test` 测量
对无关键帧的绑定进行性能分析	添加动画后性能数据骤降；首次打关键帧时卡顿	先打关键帧；添加控制器标签和预填充
GPU Override HUD 显示“Enabled (0 k)”	没有任何变形在 GPU 上运行	`R.gpu_override_census` 、 `deformerEvaluator -meshes`
缩放被连接两次，或拉伸未归一化	重复缩放；绑定缩放时肢体拉伸	仅对不继承缩放的组进行缩放；基础长度乘以根节点 scaleY
组、handle 和 locator 未锁定	“对全部内容打关键帧”会破坏绑定	`R.lockdown`
样条曲线位于起始关节之下；辅助节点位于绑定关节之下	依赖循环；引擎导出错误	两者都保持在绑定骨架之外

Handoffs

交接

Receives from scenario-maya-modeling or scenario-maya-retopology-uv: a mesh passing
```
validate(profile="model")
```
, cm, Y-up, facing +Z, feet at y = 0, centered, frozen, symmetric, pre-bent limbs, eyes forward.
Delivers to scenario-maya-deformation: the bind skeleton (joints only, one root, oriented, rotations zero, labels),
```
rig_check
```
JSON, and whether bind joints blend by constraint or through OPM (its pose readers depend on it); receives weights as data and correctives to reconnect.
Delivers to scenario-maya-animation: the rig to reference, controls at zero and tagged,
```
validate(profile="rig")
```
clean, switch list, ROM playblast, known limits.
Game rigs to scenario-maya-pipeline-scripting:
```
game_skeleton_check
```
clean, bind blends by constraint unless an OPM export was proven; they export the FBX.

从 scenario-maya-modeling 或 scenario-maya-retopology-uv 接收： 一个通过
```
validate(profile="model")
```
的网格，单位为 cm，Y-up，朝向 +Z，脚位于 y = 0，居中，已冻结，对称，肢体已预弯曲，眼睛朝前。
交付给 scenario-maya-deformation： 绑定骨架（仅关节、单一根节点、方向正确、旋转为零、带有标签）、
```
rig_check
```
JSON，以及绑定关节是使用 constraint 还是通过 OPM 进行混合（其姿势读取逻辑依赖这一信息）；接收作为数据返回的权重和需要重新连接的 corrective。
交付给 scenario-maya-animation： 可供引用的绑定、保持零位并已标记的控制器、干净的
```
validate(profile="rig")
```
、切换项列表、ROM playblast 和已知限制。
将游戏绑定交付给 scenario-maya-pipeline-scripting：
```
game_skeleton_check
```
通过；除非已证明 OPM 导出方案可用，否则绑定混合使用 constraint；由后者导出 FBX。

Maya 2027 notes

Maya 2027 注意事项

2026 renames:
```
addDL
```
,
```
multiplyDL
```
,
```
pointMatrixMultDL
```
; plain math names create unitless nodes; condition, multiplyDivide, reverse, blendMatrix unchanged.
parentMatrix (2025) has Snap and Initialize Target Offset;
```
axisFromMatrix
```
replaces the per-axis nodes.
Orient Joint: negative primary axes fixed in 2027.1; Auto orient secondary axis since 2025.
```
ikHandle
```
lists only RP, SC and spline; load spring and 2-bone solvers first. FBIK forces Serial: use HumanIK.
GPU Override: 2027.2 known issue, a crash when scrubbing with it on (disable it or the invisibility evaluator); the paper covers OpenCL on AMD and NVIDIA only, so read the HUD on Apple GPUs [verify]. Evaluator settings are per session, not saved in the scene.
Skin Tools layers block classic weight tools until deleted (scenario-maya-deformation). PySide6 only; PyMEL is not bundled.

2026 重命名：addDL、multiplyDL、pointMatrixMultDL；普通数学名称会创建无单位节点；condition、multiplyDivide、reverse 和 blendMatrix 保持不变。
parentMatrix（2025）包含 Snap 和 Initialize Target Offset；axisFromMatrix 替代了各轴节点。
Orient Joint：负向主轴问题在 2027.1 中已修复；Auto orient secondary axis 从 2025 起可用。
ikHandle 列表仅包含 RP、SC 和 spline；首先加载 spring 和 2-bone solver。FBIK 会强制使用 Serial：应使用 HumanIK。
GPU Override：2027.2 存在已知问题，启用后拖动时间线会崩溃（应禁用它或 invisibility evaluator）；论文仅涵盖 AMD 和 NVIDIA 上的 OpenCL，因此 Apple GPU 上需要读取 HUD [待验证]。Evaluator 设置仅对当前会话有效，不会保存在场景中。
Skin Tools 层会阻止使用经典权重工具，直至将其删除（scenario-maya-deformation）。仅支持 PySide6；不附带 PyMEL。

References

参考资料

```
references/procedures.md
```
: code per stage and its test; before writing rig code.
```
references/expert-notes.md
```
: judgment by expert, disagreements; when a decision is not covered here.
```
references/critique.md
```
: the rubric; at every gate.
```
references/gui-paths.md
```
: menus, Profiler, HUD; when driving the GUI.
```
references/sources.md
```
: sources, URLs, timestamps.

```
references/procedures.md
```
：各阶段对应的代码及测试；编写绑定代码前阅读。
```
references/expert-notes.md
```
：专家判断及分歧；当前文档未涵盖决策时阅读。
```
references/critique.md
```
：审查标准；每个门禁均需使用。
```
references/gui-paths.md
```
：菜单、Profiler 和 HUD 路径；操作 GUI 时阅读。
```
references/sources.md
```
：来源、URL 和时间戳。