How michaelharmonart/y-rig works
1. What this repository is
y-rig is a Maya rigging framework built on top of mGear Shifter. It extends, rather than forks, the base rig build system with custom Shifter components, reusable rigging utilities, and post-build facial rig graphs.
2. Top-level architecture
The repo is organized into three major runtime areas:
- shifter/: mGear Shifter components and custom build steps
- src/yrig/: the reusable Python library used by components and build scripts
- nxt/: NXT graph assets for facial rigging
This split is important: shifter/ is what mGear discovers during rig builds, while src/yrig/ is the package imported by both Maya and build-time tooling.
3. mGear integration boundary
The shifter/components/* folders define custom component types such as arm, leg, limb, spine, and matrix spline. Each component has a guide.py and a UI definition, which matches mGear’s Shifter component model. These components are the main authored rig modules that the artist/rig builder assembles inside mGear.
4. Build pipeline and custom steps
shifter/custom_steps/ contains the build-time hooks that run around the core mGear rig build. There are explicit pre and post steps, including paths setup, model import, control-shape application, skinning, weight splitting, cleanup, and face graph building. The architecture is therefore “standard mGear build + y-rig augmentations” rather than a standalone builder.
5. NXT facial rig subsystem
The nxt/ directory contains .nxt graphs like eye.nxt, mouth.nxt, and face_setup.nxt. These are facial-rig node graphs executed by the custom post steps, especially the face build step. This is a separate subsystem from the mGear components, used for facial behaviors and setup logic.
6. Core library package
src/yrig/ is the shared implementation layer. It provides rigging math, naming, transform utilities, Maya API wrappers, joint utilities, surface/spline helpers, control-shape handling, skinning logic, and build-context abstractions. This package is the glue that lets custom components and build steps share behavior without duplicating code.
7. Control-shape and presentation data flow
The src/yrig/control/shape_library/*.json files define reusable control shapes, and the control package includes serialization and utility code for applying them. These shapes are consumed during build steps such as apply_control_shapes.py, making control appearance part of the automated rig assembly process rather than manual Maya work.
8. Skinning and deformation subsystem
src/yrig/skin/ contains core skin application logic, serialization, visualization, and weight-splitting support. This maps directly to custom post steps like skin_model.py and split_weights.py, indicating a pipeline where imported geometry is bound and then refined after the skeleton/control rig is assembled.
9. Spline, matrix-spline, and motion utilities
src/yrig/spline/ and src/yrig/spline/matrix_spline/ implement spline-curve and matrix-spline construction used by rig components that need distributed deformation or procedural chains. These utilities likely support components such as spine, limb, and facial elements that need smooth interpolation or pinned matrix-driven motion.
10. Facial component code
src/yrig/component/bean_mouth/ and src/yrig/component/y_eye_01/ contain higher-level facial rig modules, decomposed into parts like lips, mouth corners, eyeball, eyelid, socket, and SAS. These are likely the implementation-side counterparts to the NXT facial graphs and are part of the facial rig architecture boundary.
11. Maya-facing abstraction layer
src/yrig/maya_api/ and src/yrig/build/mgear_api/ wrap Maya and mGear concepts behind internal APIs. This reduces direct dependency on raw Maya commands throughout the codebase and gives the project a stable boundary for node, attribute, control, joint, step, and rig-build operations.
12. Development and operational tooling
The repository includes maya-setup.py for bootstrapping the package into Maya, .githooks/ for local environment setup, and a GitHub Actions CI workflow. A mGear submodule is included for language-server support and compatibility, which reinforces that mGear is an external dependency rather than vendored source. The repo is therefore designed for interactive Maya development with automated dependency setup and build validation.
13. How the major data flows connect
In practice, the flow is: a developer loads src/yrig into Maya, points MGEAR_SHIFTER_COMPONENT_PATH at shifter/components, assembles a rig in mGear, and then the custom build steps use yrig utilities to apply shapes, import/skin geometry, split weights, and execute NXT facial graphs. That is the core end-to-end architecture this diagram should reflect.
Main entry points: components Components · custom_steps Build steps · build Build API · skin Skinning
Components 24
Shifter
mGear-discovered component definitions and build-time hooks.
- Components · Custom Shifter rig components assembled inside mGear.
shifter/components - Arm · Arm component definition and UI.
shifter/components/y_arm_01/guide.py - Leg · Leg component definition and UI.
shifter/components/y_leg_01/guide.py - Limb · General limb component definition and UI.
shifter/components/y_limb_01/guide.py - Spine · Spine component definition and UI.
shifter/components/y_spine_01/guide.py - Matrix spline · Spline-driven component definition and UI.
shifter/components/y_matrix_spline_01/guide.py - Build steps · Custom pre/post steps around the mGear rig build.
shifter/custom_steps - Paths setup · Pre-build environment and path configuration.
shifter/custom_steps/pre/paths.py - Import model · Post-build geometry import step.
shifter/custom_steps/post/import_model.py - Apply shapes · Post-build control-shape application step.
shifter/custom_steps/post/apply_control_shapes.py - Skin model · Post-build skin binding step.
shifter/custom_steps/post/skin_model.py - Split weights · Post-build weight splitting step.
shifter/custom_steps/post/split_weights.py - Build face · Post-build facial graph execution step.
shifter/custom_steps/post/build_face.py
Core lib
Shared Python package used by components and build steps.
- Build API · Shared build abstractions for mGear and NXT execution.
src/yrig/build - Controls · Control-shape definitions, serialization, and utilities.
src/yrig/control - Skinning · Skin application, serialization, visualization, and weight splitting.
src/yrig/skin - Spline · Curve and matrix-spline helpers for distributed motion.
src/yrig/spline - Facial parts · Shared facial component implementations for mouth and eye rigs.
src/yrig/component - Maya API · Internal wrappers around Maya nodes, attributes, and utilities.
src/yrig/maya_api - Transforms · Transform, quaternion, and matrix helpers.
src/yrig/transform
NXT graphs
Facial rig graph assets executed during post-build steps.
- NXT graphs · Face and component graph assets used in the facial build stage.
nxt
Tooling
Repository setup, CI, and development integration.
- Maya setup · Bootstraps the package into Maya for interactive development.
maya-setup.py - CI · Automated validation workflow.
.github/workflows/ci.yml - Git hooks · Local checkout, commit, and environment hooks.
.githooks
Connections 26
- Components → Arm: includes · Component package contains the arm module.
- Components → Leg: includes · Component package contains the leg module.
- Components → Limb: includes · Component package contains the limb module.
- Components → Spine: includes · Component package contains the spine module.
- Components → Matrix spline: includes · Component package contains the matrix-spline module.
- Build steps → Paths setup: pre · Pre-build path setup hook.
- Build steps → Import model: post · Imports model geometry after rig build.
- Build steps → Apply shapes: post · Applies control shapes after rig build.
- Build steps → Skin model: post · Binds skin after rig build.
- Build steps → Split weights: post · Splits weights after skinning.
- Build steps → Build face: post · Runs the facial graph build stage.
- Apply shapes → Controls: uses · Applies reusable control-shape data and helpers.
- Skin model → Skinning: uses · Delegates binding and skin logic to shared code.
- Split weights → Skinning: uses · Reuses skin weight splitting support.
- Build face → NXT graphs: executes · Loads and runs facial NXT graphs.
- Components → Facial parts: shares code · Component implementations rely on shared facial modules and utilities.
- Components → Spline: uses · Spline-based components depend on common spline helpers.
- Components → Transforms: uses · Components use transform and math helpers.
- Components → Maya API: uses · Components interact with Maya through internal adapters.
- Build API → Maya API: wraps · Build layer standardizes Maya-facing operations.
- Build API → Controls: orchestrates · Build APIs coordinate control application.
- Build API → Skinning: orchestrates · Build APIs coordinate skinning workflows.
- Build API → NXT graphs: bridges · Build APIs connect rig build to NXT facial graphs.
- Maya setup → Build API: loads · Makes the package available inside Maya.
- CI → Build steps: validates · CI checks build-step behavior and repo integration.
- Git hooks → Maya setup: supports · Repository hooks assist local environment setup.