Class OrbitControls

The OrbitControls component is used to control a camera using the OrbitControls from three.js library.
The three OrbitControls object can be accessed via the controls property.
The object being controlled by the OrbitControls (usually the camera) can be accessed via the controllerObject property.

Hierarchy (View Summary)

Implements

Properties

allowInterrupt autoFit autoRotate autoRotateSpeed autoTarget clickBackgroundToFitScene dampingFactor doubleClickToFocus enableDamping enableKeys enablePan enableRotate enableZoom gameObject guid lookAtConstraint lookAtConstraint01 maxAzimuthAngle maxPolarAngle maxZoom middleClickToFocus minAzimuthAngle minPolarAngle minZoom sourceId? targetLerpDuration zoomSpeed zoomToCursor

Accessors

activeAndEnabled cameraLerpActive context controllerObject controls destroyed enabled forward isCameraController layer lookTargetLerpActive name right scene static tag targetLerpSpeed up worldEuler worldPosition worldQuaternion worldRotation

Methods

addEventListener destroy dispatchEvent earlyUpdate? fitCamera lateUpdate? lerpTarget onAfterRender? onBeforeXR? onCollisionEnter? onCollisionExit? onCollisionStay? onEnterXR? onLeaveXR? onPausedChanged? onPointerClick? onPointerDown? onPointerEnter? onPointerExit? onPointerMove? onPointerUp? onStartInteraction onTriggerEnter? onTriggerExit? onTriggerStay? onUpdateXR? onValidate? onXRControllerAdded? onXRControllerRemoved? removeEventListener resolveGuids? setCameraAndLookTarget setCameraTargetPosition setFieldOfView setLookTargetPosition setWorldPosition setWorldQuaternion setWorldRotation startCoroutine stopCameraLerp stopCoroutine stopLookTargetLerp supportsXR? update?

Properties

allowInterrupt

allowInterrupt: boolean = true

If true user input interrupts the camera from animating to a target

Default

true

autoFit

autoFit: boolean = false

When enabled the scene will be automatically fitted into the camera view in onEnable

Default

false

autoRotate

autoRotate: boolean = false

When enabled the camera will rotate automatically

Default

false

autoRotateSpeed

autoRotateSpeed: number = 1.0

The speed at which the camera will rotate automatically. Will only be used when autoRotate is enabled

Default

1.0

autoTarget

autoTarget: boolean = true

When enabled OrbitControls will automatically raycast find a look at target in start

Default

true

clickBackgroundToFitScene

clickBackgroundToFitScene: number = 2

When enabled the camera will fit the scene to the camera view when the background is clicked the specified number of times within a short time

Default

2

dampingFactor

dampingFactor: number = 0.1

The damping factor for the camera movement. For more information see the three.js documentation

Default

0.1

doubleClickToFocus

doubleClickToFocus: boolean = true

If true the camera will focus on the target when the left mouse button is double clicked

Default

true

enableDamping

enableDamping: boolean = true

When enabled the camera movement will be damped

Default

true

enableKeys

enableKeys: boolean = false

When enabled the camera can be moved using keyboard keys. The keys are defined in the controls.keys property

Default

false

enablePan

enablePan: boolean = true

When enabled the camera can be panned

Default

true

enableRotate

enableRotate: boolean = true

When enabled the camera can be rotated

Default

true

enableZoom

enableZoom: boolean = true

When enabled the camera can be zoomed

Default

true

gameObject

gameObject: GameObject

Reference to the GameObject this component is attached to This is a three.js Object3D with additional GameObject functionality

guid

guid: string = "invalid"

Unique identifier for this component instance, used for finding and tracking components

lookAtConstraint

lookAtConstraint: null | LookAtConstraint = null

Assigning a LookAtConstraint will make the camera look at the constraint source

Default

null

lookAtConstraint01

lookAtConstraint01: number = 1

The weight of the first lookAtConstraint source

Default

1

maxAzimuthAngle

maxAzimuthAngle: number = Infinity

The maximum azimuth angle in radians

maxPolarAngle

maxPolarAngle: number = Math.PI

The maximum polar angle in radians

Default

Math.PI

maxZoom

maxZoom: number = Infinity

The maximum zoom level

Default

Infinity

middleClickToFocus

middleClickToFocus: boolean = true

If true the camera will focus on the target when the middle mouse button is clicked

minAzimuthAngle

minAzimuthAngle: number = Infinity

The minimum azimuth angle in radians

minPolarAngle

minPolarAngle: number = 0

The minimum polar angle in radians

Default

0

minZoom

minZoom: number = 0

The minimum zoom level

Default

0

OptionalsourceId

sourceId?: string

Identifier for the source asset that created this component. For example, URL to the glTF file this component was loaded from

targetLerpDuration

targetLerpDuration: number = 1

The duration in seconds it takes for the camera look ad and position lerp to reach their destination (when set via setCameraTargetPosition and setLookTargetPosition)

Default

1

zoomSpeed

zoomSpeed: number = 1

Sets the zoom speed of the OrbitControls

Default

1

zoomToCursor

zoomToCursor: boolean = false

Set to true to enable zooming to the cursor position.

Default

false

Accessors

activeAndEnabled

  • get activeAndEnabled(): boolean

    Checks if this component is currently active (enabled and part of an active GameObject hierarchy) Components that are inactive won't receive lifecycle method calls

    Returns boolean

    True if the component is enabled and all parent GameObjects are active

cameraLerpActive

  • get cameraLerpActive(): boolean

    True while the camera position is being lerped

    Returns boolean

context

  • get context(): Context

    The context this component belongs to, providing access to the runtime environment including physics, timing utilities, camera, and scene

    Returns Context

  • set context(context: Context): void

    Parameters

    Returns void

controllerObject

controls

destroyed

  • get destroyed(): boolean

    Checks if this component has been destroyed

    Returns boolean

    True if the component or its GameObject has been destroyed

enabled

  • get enabled(): boolean

    Controls whether this component is enabled Disabled components don't receive lifecycle callbacks

    Returns boolean

  • set enabled(val: boolean): void

    Parameters

    • val: boolean

    Returns void

forward

  • get forward(): Vector3

    Gets the forward direction vector (0,0,-1) of this component's GameObject in world space

    Returns Vector3

isCameraController

  • get isCameraController(): boolean

    Returns boolean

    Inherit Doc

layer

  • get layer(): number

    The layer value of the GameObject this component is attached to Used for visibility and physics filtering

    Returns number

lookTargetLerpActive

  • get lookTargetLerpActive(): boolean

    True while the camera look target is being lerped

    Returns boolean

name

  • get name(): string

    The name of the GameObject this component is attached to Used for debugging and finding objects

    Returns string

  • set name(str: string): void

    Parameters

    • str: string

    Returns void

right

  • get right(): Vector3

    Gets the right direction vector (1,0,0) of this component's GameObject in world space

    Returns Vector3

scene

  • get scene(): Scene

    Shorthand accessor for the current scene from the context

    Returns Scene

    The scene this component belongs to

static

  • get static(): boolean

    Indicates whether the GameObject is marked as static Static objects typically don't move and can be optimized by the engine

    Returns boolean

  • set static(value: boolean): void

    Parameters

    • value: boolean

    Returns void

tag

  • get tag(): string

    The tag of the GameObject this component is attached to Used for categorizing objects and efficient lookup

    Returns string

  • set tag(str: string): void

    Parameters

    • str: string

    Returns void

targetLerpSpeed

  • get targetLerpSpeed(): number

    Returns number

    Deprecated

    use targetLerpDuration instead
    The speed at which the camera target and the camera will be lerping to their destinations (if set via script or user input)

  • set targetLerpSpeed(v: number): void

    Parameters

    • v: number

    Returns void

up

  • get up(): Vector3

    Gets the up direction vector (0,1,0) of this component's GameObject in world space

    Returns Vector3

worldEuler

  • get worldEuler(): Euler

    Gets the rotation of this component's GameObject in world space as Euler angles (in radians)

    Returns Euler

  • set worldEuler(val: Euler): void

    Sets the rotation of this component's GameObject in world space using Euler angles (in radians)

    Parameters

    • val: Euler

      The world rotation Euler angles to set

    Returns void

worldPosition

  • get worldPosition(): Vector3

    Gets the position of this component's GameObject in world space.
    Note: This is equivalent to calling this.gameObject.worldPosition

    Returns Vector3

  • set worldPosition(val: Vector3): void

    Sets the position of this component's GameObject in world space

    Parameters

    • val: Vector3

      The world position vector to set

    Returns void

worldQuaternion

  • get worldQuaternion(): Quaternion

    Gets the rotation of this component's GameObject in world space as a quaternion Note: This is equivalent to calling this.gameObject.worldQuaternion

    Returns Quaternion

  • set worldQuaternion(val: Quaternion): void

    Sets the rotation of this component's GameObject in world space using a quaternion

    Parameters

    • val: Quaternion

      The world rotation quaternion to set

    Returns void

worldRotation

  • get worldRotation(): Vector3

    Gets the rotation of this component's GameObject in world space as Euler angles (in degrees)
    Note: This is equivalent to calling this.gameObject.worldRotation

    Returns Vector3

  • set worldRotation(val: Vector3): void

    Sets the rotation of this component's GameObject in world space using Euler angles (in degrees)

    Parameters

    • val: Vector3

      The world rotation vector to set (in degrees)

    Returns void

Methods

addEventListener

  • addEventListener<T extends Event>(type: string, listener: (evt: T) => any): void

    Registers an event listener for the specified event type

    Type Parameters

    Parameters

    • type: string

      The event type to listen for

    • listener: (evt: T) => any

      The callback function to execute when the event occurs

    Returns void

destroy

  • destroy(): void

    Destroys this component and removes it from its GameObject After destruction, the component will no longer receive lifecycle callbacks

    Returns void

dispatchEvent

  • dispatchEvent(evt: Event): boolean

    Dispatches an event to all registered listeners

    Parameters

    • evt: Event

      The event object to dispatch

    Returns boolean

    Always returns false (standard implementation of EventTarget)

OptionalearlyUpdate

  • earlyUpdate(): void

    Called at the beginning of each frame before regular updates. Use for logic that needs to run before standard update callbacks.

    Returns void

fitCamera

  • fitCamera(options?: FitCameraOptions): any

    Fits the camera to show the objects provided (defaults to the scene if no objects are passed in)

    Parameters

    • Optionaloptions: FitCameraOptions

    Returns any

  • fitCamera(
        objects?: Object3D<Object3DEventMap> | Object3D<Object3DEventMap>[],
        options?: Omit<FitCameraOptions, "objects">,
    ): any

    Fits the camera to show the objects provided (defaults to the scene if no objects are passed in)

    Parameters

    • Optionalobjects: Object3D<Object3DEventMap> | Object3D<Object3DEventMap>[]
    • Optionaloptions: Omit<FitCameraOptions, "objects">

    Returns any

OptionallateUpdate

  • lateUpdate(): void

    Called after all update functions have been called. Use for calculations that depend on other components being updated first.

    Returns void

lerpTarget

  • lerpTarget(position: Vector3, delta: number): void

    Parameters

    Returns void

    Deprecated

    use controls.target.lerp(position, delta)

OptionalonAfterRender

  • onAfterRender(): void

    Called after the scene has been rendered. Use for post-processing or UI updates that should happen after rendering

    Returns void

OptionalonBeforeXR

  • onBeforeXR(mode: XRSessionMode, args: XRSessionInit): void

    Called before an XR session is requested Use to modify session initialization parameters

    Parameters

    • mode: XRSessionMode

      The XR session mode being requested

    • args: XRSessionInit

      The session initialization parameters that can be modified

    Returns void

OptionalonCollisionEnter

  • onCollisionEnter(col: Collision): any

    Called when this component's collider begins colliding with another collider.

    Parameters

    • col: Collision

      Information about the collision that occurred

    Returns any

OptionalonCollisionExit

  • onCollisionExit(col: Collision): any

    Called when this component's collider stops colliding with another collider.

    Parameters

    • col: Collision

      Information about the collision that ended

    Returns any

OptionalonCollisionStay

  • onCollisionStay(col: Collision): any

    Called each frame while this component's collider is colliding with another collider

    Parameters

    • col: Collision

      Information about the ongoing collision

    Returns any

OptionalonEnterXR

OptionalonLeaveXR

OptionalonPausedChanged

  • onPausedChanged(isPaused: boolean, wasPaused: boolean): void

    Called when the context's pause state changes.

    Parameters

    • isPaused: boolean

      Whether the context is currently paused

    • wasPaused: boolean

      The previous pause state

    Returns void

OptionalonPointerClick

OptionalonPointerDown

OptionalonPointerEnter

OptionalonPointerExit

OptionalonPointerMove

OptionalonPointerUp

onStartInteraction

  • onStartInteraction(callback: Function): void

    Register callback when user starts interacting with the orbit controls

    Parameters

    Returns void

OptionalonTriggerEnter

  • onTriggerEnter(col: ICollider): any

    Called when this component's trigger collider is entered by another collider

    Parameters

    • col: ICollider

      The collider that entered this trigger

    Returns any

OptionalonTriggerExit

  • onTriggerExit(col: ICollider): any

    Called when another collider exits this component's trigger collider

    Parameters

    • col: ICollider

      The collider that exited this trigger

    Returns any

OptionalonTriggerStay

  • onTriggerStay(col: ICollider): any

    Called each frame while another collider is inside this component's trigger collider

    Parameters

    • col: ICollider

      The collider that is inside this trigger

    Returns any

OptionalonUpdateXR

OptionalonValidate

  • onValidate(prop?: string): void

    Called when a field decorated with @validate() is modified.

    Parameters

    • Optionalprop: string

      The name of the field that was changed

    Returns void

OptionalonXRControllerAdded

OptionalonXRControllerRemoved

removeEventListener

  • removeEventListener<T extends Event>(
        type: string,
        listener: (arg: T) => any,
    ): void

    Removes a previously registered event listener

    Type Parameters

    Parameters

    • type: string

      The event type the listener was registered for

    • listener: (arg: T) => any

      The callback function to remove

    Returns void

OptionalresolveGuids

  • resolveGuids(guidsMap: GuidsMap): void

    Called when this component needs to remap guids after an instantiate operation.

    Parameters

    • guidsMap: GuidsMap

      Mapping from old guids to newly generated guids

    Returns void

setCameraAndLookTarget

  • setCameraAndLookTarget(
        source: Object3D<Object3DEventMap> | Camera,
        immediateOrDuration?: number | boolean,
    ): boolean

    Sets camera target position and look direction using a raycast in forward direction of the object.

    Parameters

    • source: Object3D<Object3DEventMap> | Camera

      The object to raycast from. If a camera is passed in the camera position will be used as the source.

    • immediateOrDuration: number | boolean = false

      If true the camera target will move immediately to the new position, otherwise it will lerp. If a number is passed in it will be used as the duration of the lerp.

      This is useful for example if you want to align your camera with an object in your scene (or another camera). Simply pass in this other camera object

    Returns boolean

    true if the target was set successfully

setCameraTargetPosition

  • setCameraTargetPosition(
        position?: null | Object3D<Object3DEventMap> | Vector3Like,
        immediateOrDuration?: number | boolean,
    ): void

    Moves the camera to position smoothly.

    Parameters

    • Optionalposition: null | Object3D<Object3DEventMap> | Vector3Like

      The position in local space of the controllerObject to move the camera to. If null the camera will stop lerping to the target.

    • immediateOrDuration: number | boolean = false

      If true the camera will move immediately to the new position, otherwise it will lerp. If a number is passed in it will be used as the duration of the lerp.

    Returns void

setFieldOfView

  • setFieldOfView(
        fov: undefined | number,
        immediateOrDuration?: number | boolean,
    ): void

    Parameters

    • fov: undefined | number
    • immediateOrDuration: number | boolean = false

    Returns void

setLookTargetPosition

  • setLookTargetPosition(
        position?: null | Object3D<Object3DEventMap> | Vector3Like,
        immediateOrDuration?: number | boolean,
    ): void

    Moves the camera look-at target to a position smoothly.

    Parameters

    • position: null | Object3D<Object3DEventMap> | Vector3Like = null

      The position in world space to move the camera target to. If null the camera will stop lerping to the target.

    • immediateOrDuration: number | boolean = false

      If true the camera target will move immediately to the new position, otherwise it will lerp. If a number is passed in it will be used as the duration of the lerp.

    Returns void

setWorldPosition

  • setWorldPosition(x: number, y: number, z: number): void

    Sets the position of this component's GameObject in world space using individual coordinates

    Parameters

    • x: number

      X-coordinate in world space

    • y: number

      Y-coordinate in world space

    • z: number

      Z-coordinate in world space

    Returns void

setWorldQuaternion

  • setWorldQuaternion(x: number, y: number, z: number, w: number): void

    Sets the rotation of this component's GameObject in world space using quaternion components

    Parameters

    • x: number

      X component of the quaternion

    • y: number

      Y component of the quaternion

    • z: number

      Z component of the quaternion

    • w: number

      W component of the quaternion

    Returns void

setWorldRotation

  • setWorldRotation(x: number, y: number, z: number, degrees?: boolean): void

    Sets the rotation of this component's GameObject in world space using individual Euler angles

    Parameters

    • x: number

      X-axis rotation

    • y: number

      Y-axis rotation

    • z: number

      Z-axis rotation

    • degrees: boolean = true

      Whether the values are in degrees (true) or radians (false)

    Returns void

startCoroutine

  • startCoroutine(routine: Generator, evt?: FrameEvent): Generator

    Starts a coroutine that can yield to wait for events. Coroutines allow for time-based sequencing of operations without blocking. Coroutines are based on generator functions, a JavaScript language feature.

    Parameters

    • routine: Generator

      Generator function to start

    • evt: FrameEvent = FrameEvent.Update

      Event to register the coroutine for (default: FrameEvent.Update)

    Returns Generator

    The generator function that can be used to stop the coroutine

    Example

    Time-based sequencing of operations

    *myCoroutine() {
      yield WaitForSeconds(1); // wait for 1 second
      yield WaitForFrames(10); // wait for 10 frames
      yield new Promise(resolve => setTimeout(resolve, 1000)); // wait for a promise to resolve
    }

    Example

    Coroutine that logs a message every 5 frames

    onEnable() {
      this.startCoroutine(this.myCoroutine());
    }
    private *myCoroutine() {
      while(this.activeAndEnabled) {
        console.log("Hello World", this.context.time.frame);
        // wait for 5 frames
        for(let i = 0; i < 5; i++) yield;
      }
    }

stopCameraLerp

  • stopCameraLerp(): void

    Call to stop camera position lerping

    Returns void

stopCoroutine

  • stopCoroutine(routine: Generator, evt?: FrameEvent): void

    Stops a coroutine that was previously started with startCoroutine

    Parameters

    • routine: Generator

      The routine to be stopped

    • evt: FrameEvent = FrameEvent.Update

      The frame event the routine was registered with

    Returns void

stopLookTargetLerp

  • stopLookTargetLerp(): void

    Call to stop camera look target lerping

    Returns void

OptionalsupportsXR

  • supportsXR(mode: XRSessionMode): boolean

    Determines if this component supports a specific XR mode

    Parameters

    • mode: XRSessionMode

      The XR session mode to check support for

    Returns boolean

    True if the component supports the specified mode

Optionalupdate

  • update(): void

    Called once per frame during the main update loop. The primary location for frame-based game logic.

    Returns void

Settings

Member Visibility

On This Page

Properties
Accessors
Methods