Table of Contents

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/Orbital Cam/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.

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.

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.

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.

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.

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.

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.

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.

public void SetInputEnabled(bool enabled)

Parameters

enabled bool

SetPosition(Vector3)

Instantly set the CameraOrigin to a world coordinate.

public void SetPosition(Vector3 position)

Parameters

position Vector3

SetRotation(float)

Instantly set the local rotation of CameraOrigin to a quaternion.

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