# Rigging Standards

## Introduction

This document defines the rigging conventions adopted by OpenRig for Autodesk Maya.

---

## 1. Coordinate System & Axes

Axis conventions are defined in `openrig/conventions/config.json` and loaded at
import time by `openrig.conventions`. Projects override the file to adopt a
different studio convention without touching library code.

| Convention   | Default | Accessor                                    |
| ------------ | ------- | ------------------------------------------- |
| Aim axis     | `X`     | `get_conventions().aim_axis`                |
| Up axis      | `Y`     | `get_conventions().up_axis`                 |
| Side axis    | `Z`     | `get_conventions().side_axis`               |
| Rotate order | `xyz`   | `get_conventions().default_rotate_order`    |

**Rationale:** X-aim, Y-up, Z-side is the most common convention in rigging pipelines
and aligns with the default matrix layout for joints.

---

## 2. Side Convention

| Side   | Token | Meaning                                     |
| ------ | ----- | ------------------------------------------- |
| Left   | `l`   | Positive X side of the character            |
| Right  | `r`   | Negative X side of the character            |
| Center | `c`   | On the character's symmetry plane           |
| Middle | `m`   | Intermediate position, not strictly on-axis |

Default side is `"c"` (center), configurable via `conventions/config.json` and
accessed with `get_conventions().default_side`.

**Rule:** Left is always the character's left (positive X), not the camera's left.

---

## 3. Joint Orientation

- Joints follow the axis convention defined in Section 1: aim along **X**, up along **Y**.
- The last joint in a chain (tip joint) inherits the orientation of its parent.
- World-oriented joints are acceptable only for root and global nodes.

---

## 4. Controls & Hierarchy

A control is the animatable node that the animator directly manipulates. Its visual
representation (curve, geometry, empty transform) is not mandated by the library and is
declared in each solution's configuration.

The only universal requirement is:

> **The animatable node must read zero (or its default value) on all channels at the
> construction pose.**

The construction pose is the position at which the rig is built. It does not have to
match the pose at which the geometry is bound.

### Hierarchy options

Both of the following approaches are valid in OpenRig. How to select or configure
the approach per solution is still to be defined.

#### Option A — Group + Offset nodes

```text
<descriptor>_<side>_grp
  └── <descriptor>_<side>_offset
        └── <descriptor>_<side>_ctr
```

Explicit transform nodes absorb the initial placement so the control starts at zero.
Simple and compatible with all Maya versions, but adds nodes to the scene.

#### Option B — offsetParentMatrix

The initial placement is stored in the control's `offsetParentMatrix` attribute.
No extra nodes are needed; the control itself starts at zero in the channel box.
Cleaner hierarchy, but requires Maya 2020 or higher.

---

## 5. Node Naming

All node names must conform to the naming convention defined in `naming/config.json`.
See [naming_convention.md](naming_convention.md) for the full reference.

Quick summary of the default convention:

```text
descriptor_side_usage
upperArm_l_jnt
spine_c_ctr
```

---

## 6. Connections & Data Flow

- Prefer **matrix-based connections** over constraint nodes where possible.
  They are cheaper to evaluate and easier to inspect.
- Constraints are acceptable for legacy compatibility or cases where matrix math
  would significantly increase complexity.
- Utility nodes must follow the naming convention (`mult`, `add`, `cond`, `dmat`, etc.).

---

## 7. Build vs Scene State

- A rig must be **fully reconstructable** from its description file.
  No manual edits to the built scene should be necessary.
- Guide objects (`guide` usage token) are build-time only and must be removed or
  hidden after the rig is built.
- Any metadata needed for API access after the build must be stored as
  custom attributes on a designated metadata node.