Class OrbitalCameraSystem

Namespace

Goehler.OrbitalCam

Assembly

Goehler.OrbitalCam.Runtime.dll

The main script in the OrbitalCam system. Holds most of the properties that can be tweaked, and is the entry point for the Public API.

[AddComponentMenu("Goehler Studios/OrbitalCam/Orbital Camera System")]
[HelpURL("https://docs.goehlerstudios.com/orbitalcam/")]
[DefaultExecutionOrder(-100)]
public class OrbitalCameraSystem : MonoBehaviour

Inheritance

object

Object

Component

Behaviour

MonoBehaviour

OrbitalCameraSystem

Properties

Camera

The Unity UnityEngine.Camera attached under CameraAnchor. Found automatically at runtime.

public Camera Camera { get; }

Property Value

Camera

This value cannot be set via the inspector.

CameraAnchor

The third layer of the camera rig. This will be offset by the CurrentZoomDistance backwards and along the CurrentTiltAngle of the rig. The actual camera is attached to this object node.

public Transform CameraAnchor { get; }

Property Value

Transform

This value can only be set via the inspector.

CameraOrigin

The first layer of the camera rig. This will rotate around its y-axis.

public Transform CameraOrigin { get; }

Property Value

Transform

This value can only be set via the inspector.

CameraTarget

The second layer of the camera rig. This will have an offset along the y-axis, lifting the focus point slightly above the ground.

public Transform CameraTarget { get; }

Property Value

Transform

This value can only be set via the inspector.

CurrentPosition

The camera's current world-space position (the CameraOrigin transform position). To change it, see SetPosition(Vector3), MoveCameraTo(Vector3, float?, EasingType), or MoveCameraBy(Vector3, float?, EasingType).

public Vector3 CurrentPosition { get; }

Property Value

Vector3

This value cannot be set via the inspector.

CurrentRotationAngle

The camera's current rotation around the world Y axis (heading), in degrees [0, 360). To change it, see SetRotation(float), RotateCameraTo(float, float?, EasingType), or RotateCameraBy(float, float?, EasingType).

public float CurrentRotationAngle { get; }

Property Value

float

This value cannot be set via the inspector.

CurrentTiltAngle

The camera's current tilt angle from the target. To change it, see SetTilt(float), TiltCameraTo(float, float?, EasingType), or TiltCameraBy(float, float?, EasingType).

public float CurrentTiltAngle { get; }

Property Value

float

This value cannot be set via the inspector.

CurrentZoomDistance

The camera's current distance from the target. (Or the camera's current size, if orthographic). To change it, see SetZoom(float), ZoomCameraTo(float, float?, EasingType), or ZoomCameraBy(float, float?, EasingType).

public float CurrentZoomDistance { get; }

Property Value

float

This value cannot be set via the inspector.

EdgeScrollDirection

Edge-scroll direction; each axis is -1, 0, or 1. Zero when not edge-scrolling. Diagonals set both axes.

public Vector2 EdgeScrollDirection { get; }

Property Value

Vector2

FollowTerrainHeightSpeed

The speed multiplier for the automatic adjustment of origin height to the terrain surface.

public float FollowTerrainHeightSpeed { get; }

Property Value

float

This value can only be set via the inspector.

IsDragOrbiting

True while a drag-to-orbit gesture is held.

public bool IsDragOrbiting { get; }

Property Value

bool

IsDragPanning

True while a drag-to-pan gesture is held. False while following a target (pan input is ignored then).

public bool IsDragPanning { get; }

Property Value

bool

IsEdgeScrolling

True while edge-scrolling is active. False while following a target or while a scripted move animation is playing.

public bool IsEdgeScrolling { get; }

Property Value

bool

IsPointerPositionAvailable

True when an enabled adapter is reporting a pointer position (mouse present, touch active).

public bool IsPointerPositionAvailable { get; }

Property Value

bool

IsPointerZooming

True only on frames where the pointer scroll wheel drove a zoom. Unlike IsZoomTransitioning, this ignores keyboard zoom, animated/scripted zoom (cutscenes, animation events), and the initial pose settle. The cursor uses this so the zoom cursor only appears for direct scroll input.

public bool IsPointerZooming { get; }

Property Value

bool

IsZoomTransitioning

True while the zoom distance is actively changing this frame (pinch or scroll plus the easing tail). Touch drag-to-pan reads this to re-anchor its grab point so a moving projection can't destabilize the pan.

public bool IsZoomTransitioning { get; }

Property Value

bool

This value cannot be set via the inspector.

MaxMouseMoveSpeed

The maximum allowed movespeed while grabbing with the pointer.

public float MaxMouseMoveSpeed { get; }

Property Value

float

This value can only be set via the inspector.

MaxTiltAngle

The maximum tilt angle (looking down) that the camera can be set to. Inspector range is [1°, 88°]; values above 88° risk gimbal lock when the camera looks straight down.

public float MaxTiltAngle { get; set; }

Property Value

float

This value can be set via the inspector or at runtime.

MaxZoomDistance

The maximum allowed distance that the CameraAnchor can be from the CameraTarget.

public float MaxZoomDistance { get; }

Property Value

float

This value can only be set via the inspector.

MinTiltAngle

The minimum tilt angle (looking down) that the camera can be set to. Inspector range is [1°, 88°]; runtime values can be set outside that range.

public float MinTiltAngle { get; set; }

Property Value

float

This value can be set via the inspector or at runtime.

MinZoomDistance

The minimum allowed distance that the CameraAnchor can get towards the CameraTarget.

public float MinZoomDistance { get; }

Property Value

float

This value can only be set via the inspector.

MouseRotateSpeed

The rotation speed multiplier while rotation with the pointer.

public float MouseRotateSpeed { get; }

Property Value

float

This value can only be set via the inspector.

PinchZoomDeadzone

Dead-zone (fraction of pinch scale change) the pinch must exceed before zoom engages.

public float PinchZoomDeadzone { get; }

Property Value

float

This value can only be set via the inspector.

PinchZoomSmoothTime

Smoothing time (seconds) for the pinch scale source before the zoom delta is computed. 0 = instant.

public float PinchZoomSmoothTime { get; }

Property Value

float

This value can only be set via the inspector.

PointerMoveSmoothTime

Smoothing time (seconds) for pointer-style movement, applied at the input source. 0 = instant.

public float PointerMoveSmoothTime { get; }

Property Value

float

This value can only be set via the inspector.

PointerScreenPosition

The pointer position in screen pixels, from the first enabled adapter that provides one. Zero when none is available.

public Vector2 PointerScreenPosition { get; }

Property Value

Vector2

PointerZoomDirection

Direction of the pointer-driven zoom while IsPointerZooming: positive = zooming out (distance increasing), negative = zooming in. Zero otherwise. Same sign convention as ZoomDirection.

public float PointerZoomDirection { get; }

Property Value

float

RotateStepWorldOffset

Shifts the rotation snap grid. With a 90° step and 45° offset, snaps land on the diagonals (45/135/225/315).

public float RotateStepWorldOffset { get; set; }

Property Value

float

This value can be set via the inspector or at runtime.

ShowRaycasts

For debugging purposes. Toggle this on to see the rays used for the height adjustment calculations in the game view.

public bool ShowRaycasts { get; }

Property Value

bool

This value can only be set via the inspector.

StepAnimationTime

The default animation time for step rotation and for any animated transitions methods.

public float StepAnimationTime { get; }

Property Value

float

This value can only be set via the inspector.

TerrainLayerMask

The layer mask controlling which objects the raycasts will collide with, while determining the height of the terrain.

public LayerMask TerrainLayerMask { get; }

Property Value

LayerMask

This value can only be set via the inspector.

TiltStepWorldOffset

Shifts the tilt snap grid. With a 10° step and 0° offset, snaps land on multiples of 10° (0/10/20/...).

public float TiltStepWorldOffset { get; set; }

Property Value

float

This value can be set via the inspector or at runtime.

TouchRotateDeadzone

Dead-zone (fraction of screen width) the two-finger centroid must travel from gesture start before rotation engages. Resolution-independent; matches how rotate speed is normalized by Screen.width.

public float TouchRotateDeadzone { get; }

Property Value

float

This value can only be set via the inspector.

TouchRotateSmoothTime

Smoothing time (seconds) for two-finger rotation, applied at the touch source. Independent of the pointer rotate smoothing so mouse and touch can differ. 0 = raw.

public float TouchRotateSmoothTime { get; }

Property Value

float

This value can only be set via the inspector.

UseWorldSnapForRotateStep

When true, step rotation snaps the camera to a world-aligned grid instead of rotating relatively from the current heading.

public bool UseWorldSnapForRotateStep { get; set; }

Property Value

bool

This value can be set via the inspector or at runtime.

UseWorldSnapForTiltStep

When true, step tilt snaps the camera to a world-aligned grid. Tilt steps that would land outside the [MinTiltAngle, MaxTiltAngle] range are skipped.

public bool UseWorldSnapForTiltStep { get; set; }

Property Value

bool

This value can be set via the inspector or at runtime.

ZoomDirection

Zoom direction while IsZoomTransitioning: positive = zooming out (distance increasing), negative = zooming in. Zero when not transitioning.

public float ZoomDirection { get; }

Property Value

float

Methods

ClearFollowTarget()

Clear the follow target and restore normal movement input.

public void ClearFollowTarget()

GetState()

Capture the camera's current state (position, Y-rotation, tilt, and zoom) into a serializable OrbitalCameraState. The result works with UnityEngine.JsonUtility for save games or persistent camera state.

public OrbitalCameraState GetState()

Returns

OrbitalCameraState

MoveCameraBy(Vector3)

public void MoveCameraBy(Vector3 offset)

Parameters

offset Vector3

MoveCameraBy(Vector3, float?, EasingType)

Animate the CameraOrigin by an offset in world coordinates. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void MoveCameraBy(Vector3 offset, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

offset Vector3

animationTime float?

easing EasingType

MoveCameraByLocal(Vector3)

public void MoveCameraByLocal(Vector3 offset)

Parameters

offset Vector3

MoveCameraByLocal(Vector3, float?, EasingType)

Animate the CameraOrigin by an offset in local coordinates. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void MoveCameraByLocal(Vector3 offset, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

offset Vector3

animationTime float?

easing EasingType

MoveCameraTo(Vector3)

public void MoveCameraTo(Vector3 destination)

Parameters

destination Vector3

MoveCameraTo(Vector3, float?, EasingType)

Animate the CameraOrigin from its current position to the destination in world coordinates. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void MoveCameraTo(Vector3 destination, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

destination Vector3

animationTime float?

easing EasingType

MoveCameraUpByLocal(float)

public void MoveCameraUpByLocal(float distance)

Parameters

distance float

MoveCameraUpByLocal(float, float?, EasingType)

Animate the CameraOrigin upwards by a distance in local coordinates. Use a negative distance to move down. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void MoveCameraUpByLocal(float distance, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

distance float

animationTime float?

easing EasingType

RotateAndTiltCameraBy(Vector2)

public void RotateAndTiltCameraBy(Vector2 inputVector)

Parameters

inputVector Vector2

RotateAndTiltCameraBy(Vector2, float?, EasingType)

Animate the CameraOrigins rotation and tilt by a Vector2 offset in euler angles. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void RotateAndTiltCameraBy(Vector2 inputVector, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

inputVector Vector2

animationTime float?

easing EasingType

RotateAndTiltCameraTo(Vector2)

public void RotateAndTiltCameraTo(Vector2 inputVector)

Parameters

inputVector Vector2

RotateAndTiltCameraTo(Vector2, float?, EasingType)

Animate the CameraOrigins rotation and tilt to specific euler angles provided by a Vector2 representation. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void RotateAndTiltCameraTo(Vector2 inputVector, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

inputVector Vector2

animationTime float?

easing EasingType

RotateCameraBy(float)

public void RotateCameraBy(float angle)

Parameters

angle float

RotateCameraBy(float, float?, EasingType)

Animate the CameraOrigins horizontal rotation by a float amount in euler angles. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void RotateCameraBy(float angle, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

angle float

animationTime float?

easing EasingType

RotateCameraTo(float)

public void RotateCameraTo(float amount)

Parameters

amount float

RotateCameraTo(float, float?, EasingType)

Animate the CameraOrigins horizontal rotation to a specific euler angle in world coordinates. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void RotateCameraTo(float amount, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

amount float

animationTime float?

easing EasingType

SetFollowTarget(Transform)

Make the camera follow a transform. The CameraOrigin lerps toward the target each frame at the configured follow speed. Movement input is disabled while a target is set; rotation, tilt, and zoom remain active. Passing null clears the follow target, same as ClearFollowTarget().

public void SetFollowTarget(Transform target)

Parameters

target Transform

SetInputEnabled(bool)

Enables or disables every InputAdapter in the camera's children. Use this to disable player input during cutscenes. The camera runs on unscaled time and ignores Time.timeScale, so this is also the way to freeze camera control while your game is paused. Disabling remembers each adapter's prior enabled state; re-enabling restores it, so adapters you keep disabled by design stay disabled. Calling this with true when input wasn't disabled does nothing.

public void SetInputEnabled(bool inputEnabled)

Parameters

inputEnabled bool

SetPosition(Vector3)

Instantly set the CameraOrigin to a world coordinate.

public void SetPosition(Vector3 position)

Parameters

position Vector3

SetRotation(float)

Instantly set the CameraOrigins heading to a world-space Y euler angle in degrees.

public void SetRotation(float degrees)

Parameters

degrees float

SetState(OrbitalCameraState)

Restore the camera's state from a previously captured OrbitalCameraState. Position is clamped to the bounding box (if enabled), tilt to the configured tilt range, and zoom to the configured zoom range. So a state captured under different limits won't fail; it'll snap to the nearest valid value.

public void SetState(OrbitalCameraState state)

Parameters

state OrbitalCameraState

Remarks

Follow target is not saved with the snapshot. If your game tracks a follow target across save/load, restore it after this call by passing the appropriate UnityEngine.Transform to SetFollowTarget(Transform).

SetTilt(float)

Instantly set the CurrentTiltAngle to a specific euler angle.

public void SetTilt(float angle)

Parameters

angle float

SetZoom(float)

Instantly set the CurrentZoomDistance to a specific distance from the target.

public void SetZoom(float distance)

Parameters

distance float

TiltCameraBy(float)

public void TiltCameraBy(float angle)

Parameters

angle float

TiltCameraBy(float, float?, EasingType)

Animate the CameraOrigins vertical tilt by a float amount in euler angles. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void TiltCameraBy(float angle, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

angle float

animationTime float?

easing EasingType

TiltCameraTo(float)

public void TiltCameraTo(float amount)

Parameters

amount float

TiltCameraTo(float, float?, EasingType)

Animate the CameraOrigins vertical tilt to a specific euler angle from the ground. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void TiltCameraTo(float amount, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

amount float

animationTime float?

easing EasingType

ZoomCameraBy(float)

public void ZoomCameraBy(float distance)

Parameters

distance float

ZoomCameraBy(float, float?, EasingType)

Animate the CurrentZoomDistance by a specific distance from its current position. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void ZoomCameraBy(float distance, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

distance float

animationTime float?

easing EasingType

ZoomCameraTo(float)

public void ZoomCameraTo(float distance)

Parameters

distance float

ZoomCameraTo(float, float?, EasingType)

Animate the CurrentZoomDistance to a specific distance from the target. If no animationTime is provided, the default StepAnimationTime will be used. The easing curve defaults to EaseInOut.

public void ZoomCameraTo(float distance, float? animationTime = null, EasingType easing = EasingType.EaseInOut)

Parameters

distance float

animationTime float?

easing EasingType

Events

OnOrbitDragEnded

Raised when a pointer/touch drag-to-orbit gesture ends (including when input is disabled mid-drag).

public event Action OnOrbitDragEnded

Event Type

Action

OnOrbitDragStarted

Raised when a pointer/touch drag-to-orbit gesture begins.

public event Action OnOrbitDragStarted

Event Type

Action

OnPanDragEnded

Raised when a pointer/touch drag-to-pan gesture ends (including when input is disabled mid-drag).

public event Action OnPanDragEnded

Event Type

Action

OnPanDragStarted

Raised when a pointer/touch drag-to-pan gesture begins. Suppressed while following a target.

public event Action OnPanDragStarted

Event Type

Action