@masatomakino/threejs-billboard
    Preparing search index...

    Class CameraChaser

    Provides horizontal-only camera following functionality for Three.js objects.

    CameraChaser enables objects to rotate around the Y-axis to face the camera horizontally, while maintaining their vertical orientation. This is particularly useful for UI elements, signs, or billboards that should face the camera but remain upright.

    • Y-axis rotation only: Objects rotate left/right to face camera, but stay upright
    • Optional activation: Camera chasing must be explicitly enabled
    • Automatic integration: Works with Three.js render loop via onBeforeRender
    • Resource management: Proper cleanup to avoid memory leaks

    CameraChaser is automatically integrated with mesh-based billboard classes such as BillboardPlane, SharedStagePlaneMesh, and MultiViewPixiPlaneMesh. For full camera facing on all axes, use the Billboard class (Sprite-based) instead.

    • Y-axis rotation only: No X-axis or Z-axis rotation
    • Gimbal lock potential: Rapid rotation when camera crosses object's poles
    • Camera height restrictions: Best to limit camera's Y movement for smooth rotation
    // Usage with BillboardPlane
    const planeBillboard = new BillboardPlane("./texture.png", 1.0);
    planeBillboard.cameraChaser.isLookingCameraHorizontal = true;

    // Usage with SharedStagePlaneMesh
    const sharedPlane = new SharedStagePlaneMesh(sharedMaterial, textureArea, 1.0);
    sharedPlane.cameraChaser.isLookingCameraHorizontal = true;

    // Usage with MultiViewPixiPlaneMesh
    const multiViewPlane = new MultiViewPixiPlaneMesh(multiViewOptions);
    multiViewPlane.cameraChaser.isLookingCameraHorizontal = true;

    // Manual usage with any Object3D
    const mesh = new Mesh(geometry, material);
    const chaser = new CameraChaser(mesh);
    chaser.isLookingCameraHorizontal = true;

    // Don't forget to dispose when done
    chaser.dispose();
    Index

    Constructors

    constructor

    Properties

    isLookingCameraHorizontal needUpdateWorldPosition

    Methods

    dispose

    Constructors

    • Creates a new CameraChaser instance for the specified target object.

      The constructor automatically hooks into the target's onBeforeRender callback to perform camera following calculations. The original onBeforeRender function is preserved and can be restored via the dispose method.

      Parameters

      • target: Object3D

        The Three.js object that should follow the camera

      Returns CameraChaser

      const mesh = new Mesh(geometry, material);
      const chaser = new CameraChaser(mesh);

      // Enable camera following
      chaser.isLookingCameraHorizontal = true;

      // Add to scene
      scene.add(mesh);

    Properties

    isLookingCameraHorizontal: boolean = false

    Controls whether horizontal camera following is enabled.

    When set to true, the target object will rotate around the Y-axis to face the camera horizontally on each frame. When false, no rotation occurs.

    false

    // Enable camera chasing
    cameraChaser.isLookingCameraHorizontal = true;

    // Disable camera chasing
    cameraChaser.isLookingCameraHorizontal = false;
    needUpdateWorldPosition: boolean = false

    Flag indicating whether the world position cache needs updating.

    Set this to true if the target object's position has changed and you want the camera chaser to recalculate the world position on the next frame. Automatically reset to false after the update.

    // After moving the object
    object.position.set(10, 0, 5);
    cameraChaser.needUpdateWorldPosition = true;

    Methods

    • Releases resources and restores the target object's original state.

      This method should be called when the CameraChaser is no longer needed to prevent memory leaks and restore the target's original onBeforeRender function. After calling dispose, the CameraChaser instance should not be used.

      Returns void

      // Clean up when removing from scene
      scene.remove(mesh);
      cameraChaser.dispose();

      // Or when switching camera chasing off permanently
      cameraChaser.dispose();

    Settings

    Member Visibility

    On This Page

    Key FeaturesUsage with Billboard ClassesImportant Limitations
    Constructors
    Properties
    Methods