Cinemachine: Unity's camera rigging package, and how its branches are organised

What Cinemachine actually takes off your plate

Cinemachine is described in one line as smart camera tools for passionate creators, and the About section gives the functional claim: it is a suite of modules for operating the Unity camera, and it solves the complex mathematics and logic of tracking targets, composing, blending, and cutting between shots.

That list is the product. Target tracking is the hard part of a camera system, because a camera that follows a character has to decide what to look at, how to frame it, and how to behave when the target is destroyed or the framing would clip through geometry. Composing is the part where more than one subject has to be held in a frame with a rule about which one dominates. Blending is the transition, where one shot gives way to another without the jump a hard cut produces. Cutting is the decision to interrupt a blend and take the other shot.

The stated benefit is in the engineering time rather than the runtime. The readme says Cinemachine is designed to significantly reduce the number of time-consuming manual manipulations and script revisions that take place during development.

The audience is therefore Unity developers doing third-person or cinematic work, and the interesting part for an engineer is that the readme is almost entirely about process rather than API. The API documentation lives in the Unity manual, not here.

The install path runs through the Unity package registry, not this repository

The installation section is short and worth quoting in substance, because it determines how you get the package and where you get it from.

Cinemachine is a supported package from Unity, and as such it can be installed from the official registry in the package manager of the Unity editor. The readme links a Cinemachine Release Procedure document, hosted on Google Docs, and notes that it is an internal document containing information to help with the release of a new version.

Three practical consequences follow. The first is that this repository is not the product you install, it is the source of the product, and the package manager is the supported route. A team that clones the repository and drops the folder into a project is off the supported path and takes on the Unity package conventions themselves.

The second is that the repository layout confirms it is a Unity package rather than a plain C# library. The top-level entries include com.unity.cinemachine/ and com.unity.cinemachine.meta, plus Projects/ and Projects.meta, which is the standard layout for a Unity package with its accompanying metadata files. There is also a .npmignore file, which is unusual for a Unity project and suggests the package is also published into an npm-style pipeline.

The third is that release coordination is a human process, not a tag. The release procedure lives in an internal document, and the branching scheme below is what the rest of the readme explains.

Three kinds of branch: main, release and releases

The Branching Strategy section is the substantive documentation in this readme, and it describes three distinct kinds of branch with different rules.

The default branch is main, and that is where the latest version of Cinemachine lives. For all other minor versions of Cinemachine, a new branch is created under release, with the examples given being release/2.9 and release/2.8, and these are described as maintenance branches.

During development, pull requests are merged directly on main and on the maintenance branches, and the readme sets a firm expectation about those branches: they should always be shippable, meaning the code compiles, the features are complete and the CI pipeline is green.

Once a release is done, a branch with the version name is created under releases, with the examples releases/2.9.4 and releases/3.0.0-pre.1. No changes are made to those branches, and they exist for reference only.

So there is a clear lifecycle: main develops, release/ holds the maintenance lines for older minor versions, and releases/ is an archive of tagged points in history. For an adopter, the practical consequence is that when a bug is fixed, the fix lands on main and on whichever release branch covers the version you are on, and the releases/ branches never receive it, so a project pinned to a releases/ snapshot is frozen.

The example names also tell you the versioning story, with 2.9, 2.8 as maintained minors and 3.0.0-pre.1 as a pre-release of the next major.

The tooling around the package: Yamato CI, coverage and doc exemptions

The top-level entries show what the surrounding engineering process looks like, which matters if you intend to work on Cinemachine rather than just use it.

There is a .yamato/ directory, which is the configuration directory for Yamato, the continuous integration system Unity uses internally. There is a codecov.yml, so coverage is tracked, and a .github/ directory for the workflows that live on GitHub. There is an appcollector.yaml, which is the manifest for Unity's internal application collection tooling, and a pvp_api_doc_exemptions.json, a file that lists API members exempted from the public API documentation rules.

That last file is a good signal about what kind of project this is. A package with a public API that has documented exemptions is a package whose API surface is treated as a contract, with a process to decide what belongs in the public surface and what does not.

The directory layout follows the same logic. Alongside the package itself there is a Projects/ directory for the Unity projects used in development and testing, and a Tools/ directory for tooling, with the package contents under com.unity.cinemachine/.

The README itself mentions no sample scenes, no API listing and no version compatibility table for Unity versions. That information is in the Unity manual and the package documentation, and the readme is candid about its own scope by covering only what is specific to this repository: what the package does, how it branches, and how it is released.

Where the readme stops, and what you have to look up elsewhere

It is worth being explicit about the limits of the published documentation here, because a reader arriving at this repository expecting an API reference will not find one.

The readme does not describe the individual components, the inspector workflow of placing a camera rig in a scene, the constraint types available for framing, the blend styles, or the event and signal mechanisms used to drive cuts. It does not state which Unity versions are supported, and it does not list a compatibility matrix, which for a camera package is a question a team will have. It does not show a single line of code or a single configuration snippet, and there is no install command to copy.

The one thing it does give is the release process, and it does that well, with the branch taxonomy, the shippable-branch rule, and the pointer to the internal release document.

The alternative for someone who needs the technical detail is the Unity documentation, since the package is installed from the official registry and documented as part of Unity's own manual. Cinemachine is not an independent open source project in the way a community library would be. It is a first-party package from Unity Technologies, published through the same channel as the rest of Unity's packages, with the source public and the release process internal. The readme's own phrasing is that Cinemachine is a supported package from Unity.

That distinction changes what you can expect from the repository. You can read the implementation, you can read how changes are organised, and you can read the release policy. What you cannot do from here is work out which API to call.

Editorial conclusion

Cinemachine fits a Unity team that wants cameras driven by targets and constraints rather than by hand-written transform maths, and it does not fit a project that has to build from a source checkout alone, since the supported route is the package manager. Before adopting it, read the branch strategy in the readme and check which release branch your Unity version pairs with, because the maintenance branches under release are where fixes land and the main branch is where the next major version is developed.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. Unity-Technologies/com.unity.cinemachine on GitHub