> For the complete documentation index, see [llms.txt](https://rigonix3d.gitbook.io/rigonix3d-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rigonix3d.gitbook.io/rigonix3d-docs/documentation/integrations/cinemachine-integration.md).

# Cinemachine Integration

Drive framing with a Cinemachine rig while keeping Rigonix's stance and aim flow.

Rigonix ships its own third-person camera (`rCameraController`), but you can drive framing through **Cinemachine 3.x** instead — and keep every stance, aim, and sprint transition working exactly as before. The integration is built on a camera *seam*, so the core never depends on Cinemachine being installed.

### How the seam works

Camera behaviour hides behind an interface, `IRigonixCameraRig`, with a shared base, `RigonixCameraRigBase`. The controller talks to the rig in **named states** ("Normal", "Crouch", "Aim", "Sprint", …) pushed onto a small **priority stack**, rather than commanding a specific camera. `rCameraController` is just one implementation of that interface; a Cinemachine rig is another. Whoever's on top of the stack wins.

```mermaid
flowchart LR
    Loco[Locomotion events] --> Ctl[RigonixController]
    Ctl -->|push/pop state keys| Rig[IRigonixCameraRig]
    Rig --> Built[rCameraController]
    Rig --> Cine[Cinemachine rig]
```

Because the controller only ever speaks in state keys, swapping the built-in camera for Cinemachine changes *nothing* upstream — locomotion still just fires `OnStanceChanged`, `OnAimingChanged`, `OnSprintChanged`.

### It's optional by construction

The integration compiles only when Cinemachine is present. Rigonix auto-detects the package (via `RigonixCinemachineDefines`) and sets a scripting define; all Cinemachine-specific code sits behind `#if` guards. No Cinemachine in the project? Everything still builds and the built-in camera is used.

### Setup

{% stepper %}
{% step %}

#### Install Cinemachine 3.x

Window → Package Manager → install **Cinemachine** (3.x). Rigonix detects it and enables the integration define automatically — give Unity a moment to recompile.
{% endstep %}

{% step %}

#### Add a CinemachineCamera per state

Create a `CinemachineCamera` for each framing you want — typically Normal, Crouch, Prone, Aim, and Sprint. Frame each one the way that state should look (distance, shoulder offset, FOV).
{% endstep %}

{% step %}

#### Add the Rigonix Cinemachine rig

Add the Rigonix Cinemachine rig component (the `RigonixCameraRigBase` implementation for Cinemachine) and map each **state key** to its `CinemachineCamera`. This is what teaches the rig which vcam represents "Aim," "Crouch," and so on.
{% endstep %}

{% step %}

#### Point the controller at the rig

Assign the Cinemachine rig as the character's camera rig instead of `rCameraController`. Since both implement `IRigonixCameraRig`, the controller doesn't know or care which one it's driving.
{% endstep %}

{% step %}

#### Press Play

Crouch, aim, and sprint — Cinemachine now blends between your vcams, driven by the same Rigonix state changes. Tune the blends in Cinemachine's Blend settings.
{% endstep %}
{% endstepper %}

{% hint style="success" %}
Because framing lives in Cinemachine now, you get its whole toolbox for free — noise/shake, custom blends, dolly tracks, impulse sources — without Rigonix having to reimplement any of it.
{% endhint %}

{% hint style="info" %}
**State priority:** camera states are a stack. A transient state (like Aim) pushed on top overrides the base stance state and pops cleanly when it ends, returning to whatever was underneath. This is why aiming while crouched returns you to the crouch framing, not the standing one.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://rigonix3d.gitbook.io/rigonix3d-docs/documentation/integrations/cinemachine-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.