Class CursorFollow

CursorFollow makes an object smoothly follow the cursor or touch position in 3D space.
The component tracks pointer movement and updates the object's position to follow it, with optional damping for smooth motion.

How It Works:
The component creates a ray from the camera through the cursor position and places the object along that ray.
By default, it maintains the object's initial distance from the camera, creating a natural cursor-following effect
that works consistently regardless of camera movement.

Key Features:

  • Smooth cursor following with configurable damping
  • Works with both mouse and touch input
  • Can follow cursor across the entire page or just within the canvas
  • Maintains consistent distance from camera by default
  • Optional surface snapping using raycasts
  • Responds to camera movement automatically

Common Use Cases:

  • Interactive 3D cursors or pointers
  • Look-at effects combined with LookAtConstraint
  • Floating UI elements that track cursor
  • Interactive product showcases
  • 3D header effects and hero sections
  • Virtual laser pointers in XR experiences

Example: Basic cursor follow with smooth damping

const follower = new Object3D();
follower.position.set(0, 0, -5); // Initial position 5 units from camera
follower.addComponent(CursorFollow, {
  damping: 0.2,        // Smooth following with 200ms damping
  keepDistance: true,  // Maintain initial distance
  useFullPage: true    // Track cursor across entire page
});
scene.add(follower);

Example: Surface-snapping cursor with raycast

const cursor = new Object3D();
cursor.addComponent(CursorFollow, {
  snapToSurface: true,  // Snap to surfaces in the scene
  keepDistance: false,  // Don't maintain distance when snapping
  damping: 0.1          // Quick, responsive movement
});
scene.add(cursor);

Example: Instant cursor following (no damping)

gameObject.addComponent(CursorFollow, {
  damping: 0,           // Instant movement
  useFullPage: false    // Only track within canvas
});

Example: Interactive 3D header that looks at cursor

const character = loadModel("character.glb");
const lookTarget = new Object3D();
lookTarget.addComponent(CursorFollow, { damping: 0.3 });
character.addComponent(LookAtConstraint, { target: lookTarget });
scene.add(lookTarget, character);

See

  • LookAtConstraint - Commonly combined with CursorFollow for look-at effects
  • PointerEvents - For more complex pointer interaction handling
  • DragControls - For dragging objects in 3D space
  • OrbitControls - For camera controls that work alongside CursorFollow
  • Context.input - The input system that provides cursor position
  • Context.physics.raycastFromRay - Used when snapToSurface is enabled

Component

Hierarchy (View Summary)

Properties

damping gameObject guid keepDistance snapToSurface sourceId? useFullPage

Accessors

[$componentName] activeAndEnabled context destroyed enabled forward layer name right scene static tag up worldEuler worldPosition worldQuaternion worldRotation

Methods

addEventListener destroy dispatchEvent earlyUpdate? onAfterRender? onBeforeRender? onBeforeXR? onCollisionEnter? onCollisionExit? onCollisionStay? onDestroy onEnterXR? onLeaveXR? onPausedChanged? onPointerClick? onPointerDown? onPointerEnter? onPointerExit? onPointerMove? onPointerUp? onTriggerEnter? onTriggerExit? onTriggerStay? onUpdateXR? onValidate? onXRControllerAdded? onXRControllerRemoved? removeEventListener resolveGuids? setWorldPosition setWorldQuaternion setWorldRotation start? startCoroutine stopCoroutine supportsXR? update? updateDistance

Properties

damping

damping: number = 0

Damping factor controlling how smoothly the object follows the cursor (in seconds).

This value determines the "lag" or smoothness of the following motion:

  • 0: Instant movement, no damping (object snaps directly to cursor position)
  • 0.1-0.2: Quick, responsive following with slight smoothing
  • 0.3-0.5: Noticeable smooth trailing effect
  • 1.0+: Slow, heavily damped movement

The damping uses delta time, so the movement speed is framerate-independent and provides consistent behavior across different devices.

Tip: For look-at effects, values between 0.2-0.4 typically feel most natural. For cursor indicators, 0.1 or less provides better responsiveness.

Default

0

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

keepDistance

keepDistance: boolean = true

Whether to maintain the object's initial distance from the camera while following the cursor.

When true (default):

  • The object stays at a constant distance from the camera, moving in a spherical arc around it
  • Creates a natural "floating at cursor position" effect
  • The object's depth remains consistent as you move the cursor around
  • Perfect for cursors, pointers, or look-at targets

When false:

  • The object's distance can change based on where the cursor projects in 3D space
  • More useful when combined with snapToSurface to follow surface geometry
  • Can create unusual depth behavior if not carefully configured

How it works: On the first update, the component measures the distance from the object to the camera. This initial distance is then maintained throughout the object's lifetime (unless updateDistance is called). The object moves along a ray from the camera through the cursor, staying at this fixed distance.

See

updateDistance to manually recalculate the distance

Default

true

snapToSurface

snapToSurface: boolean = false

When enabled, the object snaps to the surfaces of other objects in the scene using raycasting.

How it works: After positioning the object at the cursor location, a raycast is performed backwards toward the camera. If the ray hits any surface, the object is moved to that hit point, effectively "snapping" to the surface.

Use cases:

  • 3D paint or decal placement tools
  • Surface markers or waypoints
  • Interactive object placement in AR/VR
  • Cursor that follows terrain or mesh surfaces

Important notes:

  • Requires objects in the scene to have colliders for raycasting to work
  • Works best with keepDistance set to false to allow depth changes
  • Can be combined with damping for smooth surface following
  • The raycast uses the physics system's raycast functionality

Debug mode: Add ?debugcursor to your URL to visualize the raycast hits with green debug lines.

See

  • Context.physics.raycastFromRay for the underlying raycast implementation
  • keepDistance should typically be false when using surface snapping

Default

false

OptionalsourceId

sourceId?: string

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

useFullPage

useFullPage: boolean = true

Whether the object should track the cursor across the entire webpage or only within the canvas.

When true (default):

  • The object follows the cursor anywhere on the page, even outside the canvas bounds
  • Perfect for look-at effects where you want continuous tracking
  • Great for embedded 3D elements that should feel aware of the whole page
  • Example: A 3D character in a hero section that watches the cursor as you scroll

When false:

  • The object only follows the cursor when it's inside the Needle Engine canvas
  • Useful for contained experiences where the 3D element shouldn't react to external cursor movement
  • Better for multi-canvas scenarios or when you want isolated 3D interactions

Note: When enabled, the component listens to window.pointermove events to track the full-page cursor position. When disabled, it uses the context's input system which is canvas-relative.

See

Context.input.mousePositionRC for canvas-relative cursor position

Default

true

Accessors

[$componentName]

  • get "[$componentName]"(): undefined | string

    Get the original component type name before minification (available if the component is registered in the TypeStore)

    Returns undefined | string

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

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

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

layer

  • get layer(): number

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

    Returns number

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

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

OptionalonAfterRender

  • onAfterRender(): void

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

    Returns void

OptionalonBeforeRender

  • onBeforeRender(frame: null | XRFrame): void

    Called immediately before the scene is rendered.

    Parameters

    • frame: null | XRFrame

      Current XRFrame if in an XR session, null otherwise

    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

onDestroy

  • onDestroy(): void

    Called when the component is destroyed. Use for cleanup operations like removing event listeners

    Returns void

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

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

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

Optionalstart

  • start(): void

    Called once at the beginning of the first frame after the component is enabled. Use for initialization that requires other components to be awake.

    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;
      }
    }

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

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

updateDistance

  • updateDistance(force?: boolean): void

    Manually recalculates the distance between the object and the camera.

    By default, the distance is calculated once when the component starts and then maintained when keepDistance is enabled. Use this method to update the reference distance if the camera or object has moved significantly.

    Use cases:

    • After teleporting the camera or object
    • When switching between different camera positions
    • After zoom operations that change the desired following distance
    • Dynamically adjusting the cursor's depth in response to user input

    Parameters

    • force: boolean = false

      If true, forces a recalculation even if keepDistance is enabled and distance was already set

    Returns void

    Example: Recalculate distance after camera movement

    const cursorFollow = gameObject.getComponent(CursorFollow);
    camera.position.set(0, 0, 10); // Move camera
    cursorFollow?.updateDistance(true); // Update the reference distance

Settings

Member Visibility

On This Page

Properties
Accessors
Methods