or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

boundaries-constraints.mdcamera-fitting.mdcamera-movement.mdcore-controls.mdevent-system.mdindex.mdinput-configuration.mdstate-management.md
tile.json

core-controls.mddocs/

Core Controls

Fundamental camera control functionality including construction, initialization, lifecycle management, and basic configuration properties.

Capabilities

CameraControls Constructor

Creates a new camera controls instance for the specified camera and DOM element.

/**
 * 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
);

Usage Examples:

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

Static Installation Method

Injects Three.js dependencies required for camera controls functionality.

/**
 * 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;

Usage Examples:

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

Static Utility Methods

Utility methods for Three.js object analysis and bounding sphere creation.

/**
 * 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;

Core Properties

Essential properties for camera controls functionality and status.

// 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

Property Details:

  • camera: The Three.js camera being controlled (can be changed)
  • enabled: Whether controls respond to user input (default: true)
  • active: Read-only property indicating if controls are currently updating
  • currentAction: Read-only current action being performed (bit flags from ACTION constants)
  • smoothTime: Transition smoothing time in seconds for programmatic movements
  • draggingSmoothTime: Transition smoothing time during user dragging
  • maxSpeed: Maximum transition speed (units per second)
  • restThreshold: Threshold for rest event firing as camera slows down
  • dragToOffset: Whether dragging moves relative to focal offset instead of target

Lifecycle Methods

Methods for connecting, updating, and disposing of camera controls.

/**
 * 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;

Usage Examples:

// 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();
}

Control Methods

Methods for immediate control actions and pointer management.

/**
 * 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 Properties

Static properties providing access to constants and configuration.

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

Usage Example:

// 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

Properties that remain available for backwards compatibility but are deprecated.

// 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

Migration Examples:

// 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