Camera
Maturity: Mature · Documentation baseline:
0.4.2· Updated 2026-10-14The 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.
Runtime model
Section titled “Runtime model”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.Priorityall 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. |
Rig arbitration
Section titled “Rig arbitration”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.
Registration
Section titled “Registration”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.
Aim coupling
Section titled “Aim coupling”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.
Minimal scene assembly
Section titled “Minimal scene assembly”Main Camera Camera CinemachineBrain
CameraSystem CameraDirector
Player CameraRig AimCore CameraAimCoupler VCam_Explore VCam_Aim
CutsceneAnchor / SpectateAnchor CameraRig VCam_Cutscene- Configure Follow/LookAt and camera behavior on each Cinemachine camera.
- Add mode entries to each
CameraRigand choose a valid current mode. - Bind a director explicitly or let the scene director register as the
ICameraDirectorservice. - Change mode, active state, and priority from local presentation code.
StateGraph reading and control
Section titled “StateGraph reading and control”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.
Director state recovery
Section titled “Director state recovery”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.
Boundaries
Section titled “Boundaries”- Camera state is local presentation state, not network or gameplay authority.
CameraRigdoes 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.