/**
 * Controls System
 * 
 * Provides camera orbit controls for the 3D world visualization.
 * Wraps Three.js OrbitControls with additional configuration and
 * safety features.
 * 
 * @file Controls.ts
 * @author Matthew Raymer
 * @created 2023-06-29
 * @version 1.0.0
 */

import { OrbitControls } from "three-orbitcontrols-ts";
import { MathUtils, PerspectiveCamera } from "three";

/**
 * Controls class for managing camera orbit controls in the 3D world.
 * 
 * This class provides a wrapper around Three.js OrbitControls with
 * additional configuration options and safety features. It handles
 * camera movement, rotation limits, and smooth damping for better
 * user experience.
 * 
 * @class Controls
 * @author Matthew Raymer
 */
class Controls {
  /** The underlying OrbitControls instance */
  private controls: OrbitControls;

  /**
   * Creates a new Controls instance with configured orbit controls.
   * 
   * @param camera - The perspective camera to control
   * @param canvas - The HTML element to attach controls to
   * 
   * @example
   * ```typescript
   * const controls = new Controls(camera, canvas);
   * const orbitControls = controls.getControls();
   * ```
   */
  constructor(camera: PerspectiveCamera, canvas: HTMLElement) {
    this.controls = new OrbitControls(camera, canvas);

    // Enable controls
    this.controls.enabled = true;
    this.controls.autoRotate = false;

    // Control limits for better user experience
    this.controls.minPolarAngle = MathUtils.degToRad(40); // Default
    this.controls.maxPolarAngle = MathUtils.degToRad(75);

    // Smooth camera movement with damping
    this.controls.enableDamping = true;

    // Set maximum distance to prevent zooming too far out
    this.controls.maxDistance = 250;

    // Update function for animation loop
    this.controls.tick = () => this.controls.update();
  }

  /**
   * Gets the underlying OrbitControls instance.
   * 
   * @returns The OrbitControls instance for direct manipulation
   * 
   * @example
   * ```typescript
   * const orbitControls = controls.getControls();
   * orbitControls.enablePan = false; // Disable panning
   * ```
   */
  public getControls(): OrbitControls {
    return this.controls;
  }
}

export { Controls };