camera-system

Camera System

When to Use

Use this skill when:

• Implementing third-person follow camera
• Creating orbit/free-look camera
• Adding camera shake effects
• Building cinematics and cutscenes
• Managing multiple camera views
• Implementing camera transitions

Core Principles

1. Smooth Movement: Use damping/lerping for smooth camera
2. Configurable: Expose camera settings
3. Multiple Modes: Support different camera behaviors
4. Collision: Prevent camera clipping through walls
5. Transitions: Smooth camera mode switching
6. Shake Effects: Screen shake for impact

Camera System Implementation

1. Camera Components

// components/CameraTarget.ts
export class CameraTarget {
  // Marks entity as camera target
  priority: number = 0;
}

// components/CameraController.ts
export enum CameraMode {
  Follow = 'follow',
  Orbit = 'orbit',
  FirstPerson = 'first-person',
  Fixed = 'fixed',
  Cinematic = 'cinematic',
}

export class CameraController {
  mode: CameraMode = CameraMode.Follow;

  // Follow mode settings
  followDistance: number = 10;
  followHeight: number = 5;
  followDamping: number = 5;
  lookAtOffset = new Vector3(0, 1, 0);

  // Orbit settings
  orbitDistance: number = 10;
  orbitMinDistance: number = 5;
  orbitMaxDistance: number = 20;
  orbitSpeed: number = 1;
  orbitDamping: number = 5;
  orbitAngleX: number = 0; // Pitch
  orbitAngleY: number = 0; // Yaw
  orbitMinAngleX: number = -Math.PI / 3;
  orbitMaxAngleX: number = Math.PI / 3;

  // First person settings
  firstPersonHeight: number = 1.6;
  firstPersonSensitivity: number = 0.002;

  // Shake settings
  shakeIntensity: number = 0;
  shakeDuration: number = 0;
  shakeTime: number = 0;

  // Collision
  collisionEnabled: boolean = true;
  collisionRadius: number = 0.5;

  constructor(mode: CameraMode = CameraMode.Follow) {
    this.mode = mode;
  }
}

2. Camera System

// systems/CameraSystem.ts
export class CameraSystem extends UpdateSystem {
  priority = 65;
  private camera: THREE.Camera;
  private target: Entity | null = null;

  constructor(camera: THREE.Camera) {
    super();
    this.camera = camera;
  }

  update(world: World, deltaTime: number): void {
    // Find camera target
    this.updateTarget(world);

    // Update camera based on mode
    const controller = this.getController(world);
    if (!controller || !this.target) return;

    switch (controller.mode) {
      case CameraMode.Follow:
        this.updateFollowCamera(controller, deltaTime);
        break;

      case CameraMode.Orbit:
        this.updateOrbitCamera(controller, deltaTime);
        break;

      case CameraMode.FirstPerson:
        this.updateFirstPersonCamera(controller);
        break;

      case CameraMode.Fixed:
        // Fixed camera doesn't move
        break;

      case CameraMode.Cinematic:
        this.updateCinematicCamera(controller, deltaTime);
        break;
    }

    // Apply camera shake
    if (controller.shakeTime > 0) {
      this.applyCameraShake(controller, deltaTime);
    }

    // Handle collision
    if (controller.collisionEnabled) {
      this.handleCameraCollision(world, controller);
    }
  }

  private updateTarget(world: World): void {
    const targets = world.query<[Transform, CameraTarget]>([Transform, CameraTarget]);

    let highestPriority = -Infinity;
    let selectedTarget: Entity | null = null;

    targets.iterate((entity, [, target]) => {
      if (target.priority > highestPriority) {
        highestPriority = target.priority;
        selectedTarget = entity;
      }
    });

    this.target = selectedTarget;
  }

  private getController(world: World): CameraController | null {
    const controllers = world.query<[CameraController]>([CameraController]);
    const first = controllers.first();
    return first?.getComponent(CameraController) ?? null;
  }

  private updateFollowCamera(controller: CameraController, deltaTime: number): void {
    if (!this.target) return;

    const targetTransform = this.target.getComponent(Transform);
    if (!targetTransform) return;

    // Calculate desired position behind target
    const forward = new Vector3(0, 0, -1).applyQuaternion(targetTransform.rotation);
    const right = new Vector3(1, 0, 0).applyQuaternion(targetTransform.rotation);

    const desiredPosition = targetTransform.position.clone()
      .add(forward.multiplyScalar(-controller.followDistance))
      .add(new Vector3(0, controller.followHeight, 0));

    // Smoothly move camera to desired position
    const currentPosition = new Vector3(
      this.camera.position.x,
      this.camera.position.y,
      this.camera.position.z
    );

    const newPosition = new Vector3().lerpVectors(
      currentPosition,
      desiredPosition,
      1 - Math.exp(-controller.followDamping * deltaTime)
    );

    this.camera.position.set(newPosition.x, newPosition.y, newPosition.z);

    // Look at target with offset
    const lookAtPoint = targetTransform.position.clone().add(controller.lookAtOffset);
    this.camera.lookAt(lookAtPoint);
  }

  private updateOrbitCamera(controller: CameraController, deltaTime: number): void {
    if (!this.target) return;

    const targetTransform = this.target.getComponent(Transform);
    if (!targetTransform) return;

    // Calculate camera position from angles
    const x = Math.cos(controller.orbitAngleY) * Math.cos(controller.orbitAngleX);
    const y = Math.sin(controller.orbitAngleX);
    const z = Math.sin(controller.orbitAngleY) * Math.cos(controller.orbitAngleX);

    const offset = new Vector3(x, y, z).multiplyScalar(controller.orbitDistance);
    const desiredPosition = targetTransform.position.clone().add(offset);

    // Smooth movement
    const currentPosition = new Vector3(
      this.camera.position.x,
      this.camera.position.y,
      this.camera.position.z
    );

    const newPosition = new Vector3().lerpVectors(
      currentPosition,
      desiredPosition,
      1 - Math.exp(-controller.orbitDamping * deltaTime)
    );

    this.camera.position.set(newPosition.x, newPosition.y, newPosition.z);
    this.camera.lookAt(targetTransform.position);
  }

  private updateFirstPersonCamera(controller: CameraController): void {
    if (!this.target) return;

    const targetTransform = this.target.getComponent(Transform);
    if (!targetTransform) return;

    // Position camera at target position + height
    const cameraPosition = targetTransform.position.clone()
      .add(new Vector3(0, controller.firstPersonHeight, 0));

    this.camera.position.copy(cameraPosition);

    // Rotate based on target rotation
    this.camera.quaternion.copy(targetTransform.rotation);
  }

  private updateCinematicCamera(controller: CameraController, deltaTime: number): void {
    // Cinematic camera is controlled by external timeline/animation system
  }

  private applyCameraShake(controller: CameraController, deltaTime: number): void {
    controller.shakeTime -= deltaTime;

    if (controller.shakeTime <= 0) {
      controller.shakeTime = 0;
      controller.shakeIntensity = 0;
      return;
    }

    // Random shake offset
    const shake = new Vector3(
      (Math.random() - 0.5) * controller.shakeIntensity,
      (Math.random() - 0.5) * controller.shakeIntensity,
      (Math.random() - 0.5) * controller.shakeIntensity
    );

    this.camera.position.add(shake);
  }

  private handleCameraCollision(world: World, controller: CameraController): void {
    if (!this.target) return;

    const targetTransform = this.target.getComponent(Transform);
    if (!targetTransform) return;

    // Raycast from target to camera
    const direction = new Vector3()
      .subVectors(this.camera.position, targetTransform.position)
      .normalize();

    // TODO: Implement proper raycast against world geometry
    // If collision detected, move camera closer
  }

  shake(intensity: number, duration: number): void {
    const controller = this.getController(world);
    if (controller) {
      controller.shakeIntensity = intensity;
      controller.shakeDuration = duration;
      controller.shakeTime = duration;
    }
  }

  setMode(mode: CameraMode): void {
    const controller = this.getController(world);
    if (controller) {
      controller.mode = mode;
    }
  }

  getCamera(): THREE.Camera {
    return this.camera;
  }
}