Cinemachine Node

Overview

The Cinemachine Dialogue Node is the camera and cinematic control centre of the Dialogue System. It can switch virtual cameras, focus on speakers or arbitrary world targets, reset to gameplay camera, and play Unity Timeline sequences — all within the dialogue graph flow. The node's displayed title and icon update automatically based on the selected action (📷 for camera actions, 🎯 for Focus on Target, 🎬 for Timeline).

All properties shown on this node are context-sensitive — the inspector fields update dynamically based on the chosen Action.

---

Ports

Port	Direction	Capacity	Description
Previous	Input	Multi	Receives connections from any preceding node.
Next	Output	Single	Advances to the next node after the camera action (and any configured wait) completes.

---

Supported Camera Types & Completion Detection

When Wait for Camera Completion is enabled, the system automatically detects the type of Cinemachine camera assigned and selects an appropriate completion handler. No manual configuration is required — detection is based on which components exist on the camera's GameObject.

The factory checks components in the following priority order:

---

1. Dolly Camera (CinemachineSplineCart / CinemachineSplineDolly)

Detected by: CinemachineSplineCart component on the GameObject, or CinemachineSplineDolly on a CinemachineCamera.

Completion criteria: Waits until the dolly's normalised spline position reaches ≥ 95% of the path length. Progress is read directly from SplineCart.SplinePosition or SplineDolly.CameraPosition.

Best used for: Cinematic tracking shots along a pre-authored spline path. The dialogue graph advances only once the dolly has nearly reached the end of its run.

---

2. Sequencer Camera (CinemachineSequencerCamera)

Detected by: CinemachineSequencerCamera component on the GameObject.

Completion criteria: Waits until the sequencer has stepped through all child cameras and returned to the child it started on, indicating a full cycle has completed.

Best used for: Automatically stepping through a series of named shots in sequence. The graph advances once the full shot list has been cycled.

---

3. State-Driven Camera (CinemachineStateDrivenCamera)

Detected by: CinemachineStateDrivenCamera component on the GameObject.

Completion criteria: Waits for the state-driven camera to transition to a different child camera than the one active at the start, then waits a further 0.5 seconds for the blend to settle.

Best used for: Cameras that switch shot based on an animator state. The graph advances once a state transition has occurred and the resulting blend is stable.

---

4. FreeLook Camera (CinemachineOrbitalFollow)

Detected by: CinemachineOrbitalFollow component on a CinemachineCamera.

Completion criteria: Monitors the camera's world position each frame. Once movement drops below 0.01 units per frame and remains stable for 1.5 seconds, it is considered complete.

Best used for: Orbital or over-the-shoulder cameras that need to settle on a target before dialogue text appears.

---

5. Follow Camera (CinemachineFollow)

Detected by: CinemachineFollow component on a CinemachineCamera.

Completion criteria: Monitors velocity each frame. Once velocity drops below 0.02 units/second and remains stable for 1.0 second, it is considered complete.

Best used for: Standard positional follow cameras. The graph waits until the camera has caught up to its target and stopped moving before advancing.

---

6. Generic Camera (fallback)

Detected by: Any camera that does not match the above types — including plain CinemachineCamera rigs without special follow components.

Completion criteria: Waits for CinemachineBrain.IsBlending to return false, plus a minimum 0.5 second buffer to ensure the blend is truly complete.

Best used for: Static shot cameras, locked cameras, or any rig not covered by a specific handler. Essentially waits for the Cinemachine blend to finish.

---

Timeout Safety

All camera handlers respect the Use Timeout and Max Wait Time settings on the node. If a handler's completion condition is never met within the configured time limit (default: 10 seconds), the dialogue graph advances regardless and a warning is logged. Disable Use Timeout only for cameras with indeterminate completion times where you are certain they will eventually complete (e.g. a very long dolly path).

Action Types

Select the Action from the dropdown at the top of the node. The available properties change entirely based on this selection.

---

Switch Camera

Activates a specific Cinemachine virtual camera by boosting its priority to 100.

Property	Type	Description
Camera Transform Variable	TransformVar	Malbers TransformVar pointing to the virtual camera's GameObject.
Blend Time	float	Duration of the Cinemachine blend to the new camera. Informational — the actual blend is controlled by the Cinemachine Brain's blend settings.
Wait for Blend	bool	If enabled, dialogue graph pauses for the blend duration before advancing.
Wait for Camera Completion	bool	If enabled, waits for camera-specific completion (e.g. a dolly cart reaching its end position) before advancing.
Use Timeout	bool	Enables a safety timeout when waiting for camera completion. Prevents indefinite blocking.
Max Wait Time	float	Maximum seconds to wait for camera completion before advancing regardless. Default: 10.
Hide Dialogue During Camera	bool	Hides the Dialogue UI via CanvasGroup alpha while the camera is moving. Default: true.

---

Focus on Speaker

Activates the Cinemachine virtual camera assigned to a DialogueSpeaker asset.

Property	Type	Description
Target Speaker	DialogueSpeaker	The speaker whose assigned camera should become active.
+ (button)	—	Creates a new DialogueSpeaker asset inline without leaving the graph editor.
Blend Time	float	Informational blend duration reference.
Wait for Blend	bool	Pauses the graph for the blend duration before advancing.

---

Blend to Target

Directs the active camera toward a custom world-space transform target.

Property	Type	Description
Target Transform Variable	TransformVar	Malbers TransformVar pointing to the world-space target transform.
Blend Time	float	Informational blend duration reference.
Wait for Blend	bool	Pauses the graph for the blend duration before advancing.
Wait for Camera Completion	bool	Waits for camera-specific completion before advancing.
Use Timeout	bool	Enables a safety timeout on the camera completion wait.
Max Wait Time	float	Maximum seconds to wait before advancing regardless.

---

Focus on Target

Redirects the main gameplay camera's Follow and LookAt targets to any world-space TransformVar — useful for drawing the player's attention to a Point of Interest, interactable object, or any scene location. The original camera targets are stored and restored after the focus completes.

Target

Property	Type	Description
Target Transform Variable	TransformVar	The transform to focus on. Shows an inline ✅/⚠/❌ status indicator based on whether the variable has a valid runtime value.

Blend Settings

Property	Type	Description
Blend Time	float	How long the camera takes to blend from its current target to the focus target.
Wait for Blend	bool	Pauses the graph for the blend duration before continuing.

Pause Settings

Property	Type	Description
Pause Duration	float	How long (seconds) the camera holds on the target before the graph advances. 0 = no pause.
Hide Dialogue Window	bool	Hides the Dialogue UI during the focus sequence. Default: true.

Return Options (visible only when Pause Duration > 0)

Property	Type	Description
Return After Pause	bool	Automatically returns to the camera that was active before the focus once the pause ends.
Return Blend Time	float	Blend duration for the return camera transition. (Visible only when Return After Pause is enabled.)

Camera Framing (Optional)

Property	Type	Description
Look At Only	bool	Only changes the camera's LookAt target — the Follow target remains unchanged.
Focus Distance	float	Camera distance from the target (applies to CinemachineThirdPersonFollow rigs). Default: 5.
Position Offset	Vector3	World-space offset from the target's position.
Screen Offset	Vector3	Screen-space framing offset (x: horizontal, y: vertical) applied via CinemachineRotationComposer.

---

Reset to Gameplay

Restores the camera state to what it was before the dialogue began. All speaker cameras activated during the conversation are reset to priority 1, and the pre-dialogue gameplay camera is restored to its original priority.

Property	Type	Description
Blend Time	float	Informational reference for the blend duration.
Wait for Blend	bool	Pauses the graph for the blend duration before advancing.

This action is called automatically by DialogueManager.EndDialogue(). Use this node mid-graph when you need an explicit mid-conversation reset before continuing with more dialogue.

---

Play Timeline

Plays a Unity Timeline sequence via a PlayableDirector. The node shows an inline status indicator (✅ configured / ⚠ incomplete / ⚪ none) and displays the Timeline's duration once both fields are assigned.

Property	Type	Description
Playable Director	PlayableDirector	Scene reference to the PlayableDirector component that will control playback.
Timeline Asset	PlayableAsset	The Timeline asset to assign and play.
Wait for Completion	bool	Pauses the dialogue graph until the Timeline finishes playing naturally. Default: true.
Allow Skip	bool	If enabled and Wait for Completion is on, the player can press Continue to jump the Timeline to its final frame and advance.
Rewind on Re-enter	bool	Resets the Timeline to time 0 whenever this node is visited. Default: true.

---

Validation

Condition	Severity
No incoming connection	Warning
No outgoing connection	Warning
SwitchCamera: no Camera Transform Variable assigned	Error
SwitchCamera: variable assigned but runtime value is null	Warning
FocusOnSpeaker: no Target Speaker assigned	Error
FocusOnSpeaker: speaker has no camera target or custom camera	Warning
BlendToTarget: no Target Transform Variable assigned	Error
BlendToTarget: variable assigned but runtime value is null	Warning
FocusOnTarget: no Target Transform Variable assigned	Error
FocusOnTarget: variable assigned but runtime value is null	Warning
FocusOnTarget: Return After Pause enabled but Pause Duration is 0	Warning
FocusOnTarget: Focus Distance < 0.1	Warning
PlayTimeline: Director or Asset missing	Error
PlayTimeline: Timeline duration is zero or negative	Error
PlayTimeline: Allow Skip enabled without Wait for Completion	Warning
Any blend time is negative	Warning

---

Usage Tips

• Opening cinematics — connect Start Node → Cinemachine Node (PlayTimeline or SwitchCamera) → first dialogue line. The dialogue UI stays hidden during the camera action if Hide Dialogue During Camera is enabled, giving a clean cinematic feel.

• Per-speaker framing — use FocusOnSpeaker before each character's dialogue line for automatic shot/reverse-shot coverage. The speaker's camera is deactivated automatically when dialogue ends.

• Point of Interest callouts — use FocusOnTarget with a PointOfInterest TransformVar to pan the camera to a map location mid-conversation, then return to the speaker with Return After Pause.

• Timeline skip requires Wait for Completion — enabling Allow Skip without Wait for Completion has no effect. The validator will warn you if this misconfiguration is detected.

• Rewind on Re-enter — leave this enabled unless your Timeline is designed to resume from where it left off (e.g. a looping ambient sequence). For one-shot cinematics it should always be true.

• Camera restoration is automatic — you do not need to add a ResetToGameplay node at the end of every graph. DialogueManager.EndDialogue() handles camera restoration. Use the explicit Reset node only when you need a mid-conversation camera reset before continuing.