Core Controls

/**
 * Creates a new CameraControls instance
 * @param camera - Three.js perspective or orthographic camera to control
 * @param domElement - HTML element for input handling (optional, can connect later)
 */
constructor(
  camera: THREE.PerspectiveCamera | THREE.OrthographicCamera,
  domElement?: HTMLElement
);

import * as THREE from 'three';
import CameraControls from 'camera-controls';

CameraControls.install({ THREE });

// With DOM element
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const controls = new CameraControls(camera, renderer.domElement);

// Without DOM element (connect later)
const controls2 = new CameraControls(camera);
controls2.connect(renderer.domElement);

/**
 * Installs Three.js dependencies required for CameraControls
 * Must be called before creating any CameraControls instances
 * @param libs - Object containing Three.js classes and utilities
 */
static install(libs: { THREE: THREESubset }): void;

// Full Three.js installation
import * as THREE from 'three';
import CameraControls from 'camera-controls';

CameraControls.install({ THREE });

// Tree-shaking minimal installation
import {
  Vector2, Vector3, Vector4, Quaternion, Matrix4,
  Spherical, Box3, Sphere, Raycaster
} from 'three';

const subsetOfTHREE = {
  Vector2, Vector3, Vector4, Quaternion, Matrix4,
  Spherical, Box3, Sphere, Raycaster
};

CameraControls.install({ THREE: subsetOfTHREE });

/**
 * Creates a bounding sphere for a Three.js object
 * @param object3d - Three.js object to create bounding sphere for
 * @param out - Optional output sphere to write result to
 * @returns Bounding sphere containing the object
 */
static createBoundingSphere(object3d: THREE.Object3D, out?: THREE.Sphere): THREE.Sphere;

// Camera and control state
camera: THREE.PerspectiveCamera | THREE.OrthographicCamera;
enabled: boolean;
active: boolean; // read-only
currentAction: ACTION; // read-only

// Control configuration
smoothTime: number; // default: 0.25
draggingSmoothTime: number; // default: 0.125
maxSpeed: number; // default: Infinity
restThreshold: number; // default: 0.01
dragToOffset: boolean; // default: false

/**
 * Connect controls to a DOM element for input handling
 * @param domElement - HTML element to attach event listeners to
 */
connect(domElement: HTMLElement): void;

/**
 * Update camera controls - call in animation loop
 * @param delta - Time elapsed since last update in seconds
 * @returns True if camera position/orientation changed
 */
update(delta: number): boolean;

/**
 * Dispose of controls and remove all event listeners
 * Call when controls are no longer needed to prevent memory leaks
 */
dispose(): void;

// Basic animation loop
const clock = new THREE.Clock();
function animate() {
  const delta = clock.getDelta();
  const updated = cameraControls.update(delta);
  
  // Optional: only render when camera changes
  if (updated) {
    renderer.render(scene, camera);
  }
  
  requestAnimationFrame(animate);
}

// Cleanup when done
function cleanup() {
  cameraControls.dispose();
}

/**
 * Force cancel any current user dragging operation
 */
cancel(): void;

/**
 * Lock the pointer for first-person style controls (experimental)
 */
lockPointer(): void;

/**
 * Unlock the pointer (experimental)
 */
unlockPointer(): void;

/**
 * Detach all internal event handlers to disable drag control
 */
disconnect(): void;

/**
 * Static property providing access to ACTION constants
 */
static ACTION: typeof ACTION;

// Configure mouse buttons using static ACTION constants
cameraControls.mouseButtons.left = CameraControls.ACTION.ROTATE;
cameraControls.mouseButtons.right = CameraControls.ACTION.TRUCK;
cameraControls.mouseButtons.middle = CameraControls.ACTION.DOLLY;

// Deprecated properties - use alternatives instead
verticalDragToForward: boolean; // DEPRECATED: Use mouseButtons.left = CameraControls.ACTION.SCREEN_PAN
dampingFactor: number; // DEPRECATED: Use smoothTime instead
draggingDampingFactor: number; // DEPRECATED: Use draggingSmoothTime instead

// OLD (deprecated):
cameraControls.verticalDragToForward = true;
cameraControls.dampingFactor = 0.1;
cameraControls.draggingDampingFactor = 0.05;

// NEW (recommended):
cameraControls.mouseButtons.left = CameraControls.ACTION.SCREEN_PAN;
cameraControls.smoothTime = 0.25; // In seconds, not factor
cameraControls.draggingSmoothTime = 0.125; // In seconds, not factor