# michaelharmonart/y-rig architecture

> Architecture diagram of the GitHub repository michaelharmonart/y-rig, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/michaelharmonart/y-rig
- Repository: https://github.com/michaelharmonart/y-rig

## Overview

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: [`shifter/components`](https://github.com/michaelharmonart/y-rig/tree/main/shifter/components) (Components), [`shifter/custom_steps`](https://github.com/michaelharmonart/y-rig/tree/main/shifter/custom_steps) (Build steps), [`src/yrig/build`](https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/build) (Build API), [`src/yrig/skin`](https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/skin) (Skinning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_shifter["Shifter"]
  node_node_shifter_components["Components<br/>mGear modules"]
  node_node_shifter_arm["Arm<br/>[guide.py]"]
  node_node_shifter_leg["Leg<br/>[guide.py]"]
  node_node_shifter_limb["Limb<br/>[guide.py]"]
  node_node_shifter_spine["Spine<br/>[guide.py]"]
  node_node_shifter_matrix_spline["Matrix spline<br/>[guide.py]"]
  node_node_shifter_steps["Build steps<br/>pipeline hooks"]
  node_node_step_paths["Paths setup<br/>pre-step<br/>[paths.py]"]
  node_node_step_import["Import model<br/>post-step<br/>[import_model.py]"]
  node_node_step_shapes["Apply shapes<br/>post-step"]
  node_node_step_skin["Skin model<br/>post-step<br/>[skin_model.py]"]
  node_node_step_split["Split weights<br/>post-step<br/>[split_weights.py]"]
  node_node_step_face["Build face<br/>post-step<br/>[build_face.py]"]
end

subgraph group_grp_core["Core lib"]
  node_node_yrig_build["Build API<br/>integration layer"]
  node_node_yrig_control["Controls<br/>control system"]
  node_node_yrig_skin["Skinning<br/>deformation system"]
  node_node_yrig_spline["Spline<br/>motion utilities"]
  node_node_yrig_components["Facial parts<br/>facial modules"]
  node_node_yrig_maya["Maya API<br/>adapter layer"]
  node_node_yrig_transform["Transforms<br/>math utilities"]
end

subgraph group_grp_nxt["NXT graphs"]
  node_node_nxt_graphs["NXT graphs<br/>facial graphs"]
end

subgraph group_grp_tooling["Tooling"]
  node_node_tooling_setup["Maya setup<br/>bootstrap script<br/>[maya-setup.py]"]
  node_node_tooling_ci["CI<br/>workflow<br/>[ci.yml]"]
  node_node_tooling_hooks["Git hooks<br/>dev tooling<br/>[.githooks]"]
end

node_node_shifter_components -->|"includes"| node_node_shifter_arm
node_node_shifter_components -->|"includes"| node_node_shifter_leg
node_node_shifter_components -->|"includes"| node_node_shifter_limb
node_node_shifter_components -->|"includes"| node_node_shifter_spine
node_node_shifter_components -->|"includes"| node_node_shifter_matrix_spline
node_node_shifter_steps -->|"pre"| node_node_step_paths
node_node_shifter_steps -->|"post"| node_node_step_import
node_node_shifter_steps -->|"post"| node_node_step_shapes
node_node_shifter_steps -->|"post"| node_node_step_skin
node_node_shifter_steps -->|"post"| node_node_step_split
node_node_shifter_steps -->|"post"| node_node_step_face
node_node_step_shapes -->|"uses"| node_node_yrig_control
node_node_step_skin -->|"uses"| node_node_yrig_skin
node_node_step_split -->|"uses"| node_node_yrig_skin
node_node_step_face -->|"executes"| node_node_nxt_graphs
node_node_shifter_components -->|"shares code"| node_node_yrig_components
node_node_shifter_components -->|"uses"| node_node_yrig_spline
node_node_shifter_components -->|"uses"| node_node_yrig_transform
node_node_shifter_components -->|"uses"| node_node_yrig_maya
node_node_yrig_build -->|"wraps"| node_node_yrig_maya
node_node_yrig_build -->|"orchestrates"| node_node_yrig_control
node_node_yrig_build -->|"orchestrates"| node_node_yrig_skin
node_node_yrig_build -->|"bridges"| node_node_nxt_graphs
node_node_tooling_setup -->|"loads"| node_node_yrig_build
node_node_tooling_ci -->|"validates"| node_node_shifter_steps
node_node_tooling_hooks -->|"supports"| node_node_tooling_setup

click node_node_shifter_components "https://github.com/michaelharmonart/y-rig/tree/main/shifter/components"
click node_node_shifter_arm "https://github.com/michaelharmonart/y-rig/blob/main/shifter/components/y_arm_01/guide.py"
click node_node_shifter_leg "https://github.com/michaelharmonart/y-rig/blob/main/shifter/components/y_leg_01/guide.py"
click node_node_shifter_limb "https://github.com/michaelharmonart/y-rig/blob/main/shifter/components/y_limb_01/guide.py"
click node_node_shifter_spine "https://github.com/michaelharmonart/y-rig/blob/main/shifter/components/y_spine_01/guide.py"
click node_node_shifter_matrix_spline "https://github.com/michaelharmonart/y-rig/blob/main/shifter/components/y_matrix_spline_01/guide.py"
click node_node_shifter_steps "https://github.com/michaelharmonart/y-rig/tree/main/shifter/custom_steps"
click node_node_step_paths "https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/pre/paths.py"
click node_node_step_import "https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/post/import_model.py"
click node_node_step_shapes "https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/post/apply_control_shapes.py"
click node_node_step_skin "https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/post/skin_model.py"
click node_node_step_split "https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/post/split_weights.py"
click node_node_step_face "https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/post/build_face.py"
click node_node_yrig_build "https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/build"
click node_node_yrig_control "https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/control"
click node_node_yrig_skin "https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/skin"
click node_node_yrig_spline "https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/spline"
click node_node_yrig_components "https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/component"
click node_node_yrig_maya "https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/maya_api"
click node_node_yrig_transform "https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/transform"
click node_node_nxt_graphs "https://github.com/michaelharmonart/y-rig/tree/main/nxt"
click node_node_tooling_setup "https://github.com/michaelharmonart/y-rig/blob/main/maya-setup.py"
click node_node_tooling_ci "https://github.com/michaelharmonart/y-rig/blob/main/.github/workflows/ci.yml"
click node_node_tooling_hooks "https://github.com/michaelharmonart/y-rig/blob/main/.githooks"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_shifter_components,node_node_shifter_arm,node_node_shifter_leg,node_node_shifter_limb,node_node_shifter_spine,node_node_shifter_matrix_spline,node_node_shifter_steps,node_node_step_paths,node_node_step_import,node_node_step_shapes,node_node_step_skin,node_node_step_split,node_node_step_face toneBlue
class node_node_yrig_build,node_node_yrig_control,node_node_yrig_skin,node_node_yrig_spline,node_node_yrig_components,node_node_yrig_maya,node_node_yrig_transform toneAmber
class node_node_nxt_graphs toneMint
class node_node_tooling_setup,node_node_tooling_ci,node_node_tooling_hooks toneRose
```

## Components

### Shifter

mGear-discovered component definitions and build-time hooks.

- [Components](https://github.com/michaelharmonart/y-rig/tree/main/shifter/components): mGear modules · Custom Shifter rig components assembled inside mGear. · `shifter/components`
- [Arm](https://github.com/michaelharmonart/y-rig/blob/main/shifter/components/y_arm_01/guide.py): Arm component definition and UI. · `shifter/components/y_arm_01/guide.py`
- [Leg](https://github.com/michaelharmonart/y-rig/blob/main/shifter/components/y_leg_01/guide.py): Leg component definition and UI. · `shifter/components/y_leg_01/guide.py`
- [Limb](https://github.com/michaelharmonart/y-rig/blob/main/shifter/components/y_limb_01/guide.py): General limb component definition and UI. · `shifter/components/y_limb_01/guide.py`
- [Spine](https://github.com/michaelharmonart/y-rig/blob/main/shifter/components/y_spine_01/guide.py): Spine component definition and UI. · `shifter/components/y_spine_01/guide.py`
- [Matrix spline](https://github.com/michaelharmonart/y-rig/blob/main/shifter/components/y_matrix_spline_01/guide.py): Spline-driven component definition and UI. · `shifter/components/y_matrix_spline_01/guide.py`
- [Build steps](https://github.com/michaelharmonart/y-rig/tree/main/shifter/custom_steps): pipeline hooks · Custom pre/post steps around the mGear rig build. · `shifter/custom_steps`
- [Paths setup](https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/pre/paths.py): pre-step · Pre-build environment and path configuration. · `shifter/custom_steps/pre/paths.py`
- [Import model](https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/post/import_model.py): post-step · Post-build geometry import step. · `shifter/custom_steps/post/import_model.py`
- [Apply shapes](https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/post/apply_control_shapes.py): post-step · Post-build control-shape application step. · `shifter/custom_steps/post/apply_control_shapes.py`
- [Skin model](https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/post/skin_model.py): post-step · Post-build skin binding step. · `shifter/custom_steps/post/skin_model.py`
- [Split weights](https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/post/split_weights.py): post-step · Post-build weight splitting step. · `shifter/custom_steps/post/split_weights.py`
- [Build face](https://github.com/michaelharmonart/y-rig/blob/main/shifter/custom_steps/post/build_face.py): post-step · 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](https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/build): integration layer · Shared build abstractions for mGear and NXT execution. · `src/yrig/build`
- [Controls](https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/control): control system · Control-shape definitions, serialization, and utilities. · `src/yrig/control`
- [Skinning](https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/skin): deformation system · Skin application, serialization, visualization, and weight splitting. · `src/yrig/skin`
- [Spline](https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/spline): motion utilities · Curve and matrix-spline helpers for distributed motion. · `src/yrig/spline`
- [Facial parts](https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/component): facial modules · Shared facial component implementations for mouth and eye rigs. · `src/yrig/component`
- [Maya API](https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/maya_api): adapter layer · Internal wrappers around Maya nodes, attributes, and utilities. · `src/yrig/maya_api`
- [Transforms](https://github.com/michaelharmonart/y-rig/tree/main/src/yrig/transform): math utilities · Transform, quaternion, and matrix helpers. · `src/yrig/transform`

### NXT graphs

Facial rig graph assets executed during post-build steps.

- [NXT graphs](https://github.com/michaelharmonart/y-rig/tree/main/nxt): facial graphs · Face and component graph assets used in the facial build stage. · `nxt`

### Tooling

Repository setup, CI, and development integration.

- [Maya setup](https://github.com/michaelharmonart/y-rig/blob/main/maya-setup.py): bootstrap script · Bootstraps the package into Maya for interactive development. · `maya-setup.py`
- [CI](https://github.com/michaelharmonart/y-rig/blob/main/.github/workflows/ci.yml): workflow · Automated validation workflow. · `.github/workflows/ci.yml`
- [Git hooks](https://github.com/michaelharmonart/y-rig/blob/main/.githooks): dev tooling · Local checkout, commit, and environment hooks. · `.githooks`

## Connections

- 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.
