Skip to content

Camera

Maturity: Mature · Documentation baseline: 0.4.2 · Updated 2026-10-14

The module originated in 0.3.9. Its current Runtime API is stable and usable; that history does not make it transitional or scheduled for replacement.

Camera is a local presentation module for Unity 6 and Cinemachine. It gathers CameraRig instances, selects one available rig by priority, and applies that rig’s priority to its current Cinemachine virtual camera. It does not replace Cinemachine’s orbit, damping, collision, composition, blend, or Timeline features.

project code / presentation adapter
├─ CameraRig.SetMode(modeId)
├─ CameraRig.SetPriority(value)
└─ CameraRig.SetActive(value)
↓
CameraDirector: active + enabled + current camera
↓
highest priority; newest registration wins ties
↓
winner.CurrentCamera.Priority = winner.Priority
all other registered rig cameras = 0
↓
CinemachineBrain
Type Responsibility
CameraDirector Registers rigs, arbitrates the winner, clears stale runtime priorities, exposes the active rig/camera, and can suspend scheduling.
ICameraDirector Stable interface for registration, refresh, activation, priority, scheduling suspension, and ActiveRigChanged.
CameraRig Owns a rig ID, active flag, priority, current mode ID, and a mode-to-virtual-camera table.
CameraRigCameraEntry Maps one project-defined string mode ID to one CinemachineVirtualCameraBase.
CameraAimCoupler Reads a bound Look action through InputReader, applies yaw/pitch to an AimCore transform, and optionally synchronizes another transform.

CameraDirector considers a rig only when it is active, enabled, alive, and has a camera for its current mode. Higher priority wins. If two candidates have the same priority, the one registered later wins. Every refresh clears the configured cameras of all registered rigs to priority 0, then assigns the winning camera its rig priority.

SetSchedulingSuspended(true) clears all rig priorities and reports no active rig. This is the handoff point for Timeline or another authored camera system. Resuming reruns normal arbitration from the current rig state.

Mode IDs are ordinary project strings such as Explore, Aim, Dialogue, or Spectate; CoCoFlow assigns no gameplay semantics to them. SetCamera may add or replace a mapping at runtime. SetMode clears the previous camera’s runtime priority when the selected camera changes.

A rig can reference an explicit ICameraDirector component through SetCameraDirector. When no explicit component is assigned, it resolves the director registered as ICameraDirector in CoCoServices; if that service is not ready, it waits for registration. registerOnEnable controls automatic registration, and disabling a rig unregisters it and clears its camera priorities.

This service fallback is part of the Camera module’s current behavior. It does not extend the Core Engine maturity declaration to every older Runtime/Core/*.cs service facility.

CameraAimCoupler requires explicit InputReader and Look InputActionReference bindings. It accumulates yaw and clamped pitch using Time.deltaTime, then writes the local rotation of its own transform.

When coupling is enabled:

  • a non-ancestor target receives the AimCore’s full world rotation;
  • an ancestor target receives only the horizontal yaw delta, after which the AimCore world aim is restored and its cached local angles are rebased;
  • a missing input reader/action simply produces no input update;
  • a missing sync target leaves the AimCore rotating without synchronizing another object.

There is no automatic search for input, targets, rigs, or Cinemachine cameras.

Main Camera
Camera
CinemachineBrain
CameraSystem
CameraDirector
Player
CameraRig
AimCore
CameraAimCoupler
VCam_Explore
VCam_Aim
CutsceneAnchor / SpectateAnchor
CameraRig
VCam_Cutscene
  1. Configure Follow/LookAt and camera behavior on each Cinemachine camera.
  2. Add mode entries to each CameraRig and choose a valid current mode.
  3. Bind a director explicitly or let the scene director register as the ICameraDirector service.
  4. Change mode, active state, and priority from local presentation code.

Bind CameraIntent and CameraOperator under the controlling Host in Intent Sources / Operators, and assign the same Director. The Director needs an explicit CinemachineBrain; CameraIntent reads its OutputCamera. StateLogic uses CoCoFlow.Runtime.Camera.Contracts and declares [Intent] CameraIntentData and [Operation] CameraOperation properties.

CameraIntentData.PositionX/Y/Z are world position; RotationX/Y/Z are world Euler angles in degrees. Configure the Director’s Rig Mappings with stable numeric Rig IDs and Camera IDs mapped to existing Rigs and string Mode IDs. 0 is valid; list indices and Unity InstanceIDs are unsuitable.

Each CameraOperation request writes all five properties: RigId, Active, Priority, CameraId, and SchedulingEnabled. Omitted properties do not retain previous Tick values. Active affects the selected Rig; SchedulingEnabled affects the entire Director. Missing targets reject the request without creating cameras. See Usage examples for code.

Add PersistenceContext to the Host object and enable CameraOperator’s Persistence restore switch. CameraOperator supports save/load only, with no Temporal switch. Each successful Tick captures Director.GetState in Context; SaveGame uses the latest committed Context, without recapturing at button press. Restore applies the snapshot through Director.SetState.

The snapshot includes output world pose, scheduling, and up to 64 existing Rigs with numeric IDs, active state, priority, Camera ID, and relative registration order. Restore requires the same registered Rig set, resets blending, and restores pose without Lens/FOV data or object reconstruction.

Keep scheduling enabled, or keep camera state unchanged while scheduling is suspended. Otherwise a later Brain update may overwrite a restored suspended pose. External camera controllers remain the project’s responsibility. Camera snapshots are Durable-only and excluded from Temporal history.

  • Camera state is local presentation state, not network or gameplay authority.
  • CameraRig does not write Cinemachine Follow/LookAt targets.
  • The module does not implement orbit, collision, damping, occlusion, shake, Timeline blending, IK, or weapon alignment.
  • Priority bands are project conventions; only numeric comparison and registration-order tie-breaking are framework behavior.
  • “Mature” refers to the current Runtime API and known behavior, not to a claim of optimal scheduling performance or complete Camera Editor tooling.