# Rotation Clamping Settings

Several FocalRig nodes share a common **Rotation Clamp** struct that limits how far an element can rotate from its rest pose. This page documents the shared settings.

Nodes that use Rotation Clamping:
- [Aim Chain](aim-chain.md)
- [Aim Weapon](aim-weapon.md)
- [First-Person View](first-person-view.md)
- [Spring Interp Quaternion Clamped](spring-interp-quaternion-clamped.md)

## Mode

| Mode | Description |
|------|-------------|
| **Disabled** | No clamping applied |
| **SwingTwist** | Symmetric twist and swing limits. Good for general-purpose limits where the element can rotate equally in all directions |
| **Euler** | Separate pitch, roll, and yaw limits. Good when the allowed range differs by direction, e.g. a spine element that should pitch down more than up |

## Common Properties

These properties appear regardless of the selected mode (hidden when Mode is Disabled):

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| Mode | Clamp Mode | SwingTwist | Which clamping strategy to use |
| Space | Space | Local | **Local**: the reference frame is in the local space of the element being rotated. **Global**: the reference frame is in <span class="fr-term" tabindex="0" data-tooltip-key="global-space">global space</span> |
| Reference Frame | Rotation | Identity | Orientation of the clamping coordinate system. Identity means X = forward, Y = right, Z = up in the chosen space. The Z axis is the twist/yaw axis, the X axis is the roll axis, and the Y axis is the pitch axis |

## SwingTwist Properties

Visible when Mode is set to **SwingTwist**. Both limits are symmetric (e.g. +/- 90 degrees). For asymmetric limits, use Euler mode instead.

| Property | Type | Default | Range | Description |
|----------|------|---------|-------|-------------|
| Max Twist Degrees | float | 90 | 0 to 180 | Maximum allowed twist around the Z axis, in degrees |
| Max Swing Degrees | float | 90 | 0 to 180 | Maximum allowed swing off the Z axis, in degrees |

## Euler Properties

Visible when Mode is set to **Euler**. Each axis can have an independent asymmetric range, specified as an interval (min, max).

Euler mode applies pitch, roll, and yaw in a fixed order so each axis can have its own min and max range. Pitch and yaw can go up to +/- 180 degrees. Roll is limited to +/- 90 degrees, but that is usually enough because roll is typically a smaller correction.

| Property | Type | Default | Range | Description |
|----------|------|---------|-------|-------------|
| Pitch | Interval (float) | (-45, 45) | -180 to 180 | Allowed pitch range in degrees (looking up/down, rotation around the Y axis) |
| Roll | Interval (float) | (-10, 10) | -90 to 90 | Allowed roll range in degrees (head tilt, rotation around the X axis) |
| Yaw | Interval (float) | (-90, 90) | -180 to 180 | Allowed yaw range in degrees (looking left/right, rotation around the Z axis) |

## Debug Draw

When a node exposes debug drawing and uses this shared clamp struct, the clamp visualization comes from the shared implementation below.

| Mode | Color | What it shows |
|------|-------|---------------|
| SwingTwist | <span style="color:red">Red</span> | Swing limit cone and the applied swing direction |
| SwingTwist | <span style="color:green">Green</span> | Twist limit arc/spokes and the applied twist direction |
| Euler | <span style="color:yellow">Yellow</span> | Allowed pitch/yaw surface, boundary arcs, and roll range |
| Euler | <span style="color:red">Red</span> | Applied pitch/yaw direction |
| Euler | <span style="color:green">Green</span> | Applied roll direction |