Camera System

A flexible, extensible camera system for 3D applications and games with support for multiple camera types and smooth transitions.

Features

• Modular Design: Extensible base camera class with specialized implementations
• Multiple Camera Types:
  • First Person Camera - FPS-style camera with look controls
  • Third Person Camera - Follow a target with configurable offset and rotation
  • Orbit Camera - Revolve around a target point with zoom capabilities
  • Top Down Camera - Bird's eye view with configurable height and angle
  • Isometric Camera - Fixed-angle orthographic projection
  • Side Scroller Camera - 2D-style camera with parallax support
  • Cinematic Camera - For cutscenes and directed camera movements
• Smooth Transitions: Seamlessly transition between camera types with customizable easing
• Advanced Features:
  • Camera shake effects
  • Target following with configurable smoothing
  • Screen space effects
  • Depth of field and cinematic effects
  • Event system for synchronizing camera movements with gameplay
• Configuration System: Unified configuration for all camera types with serialization support

Installation

npm install @fred/camera-system

Quick Start

import { CameraSystem, FirstPersonCamera, CameraType } from '@fred/camera-system';
import * as THREE from 'three';

// Create a Three.js camera
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);

// Initialize camera system with a First Person Camera
const cameraSystem = new CameraSystem(camera);

// Add a first person camera with configuration
const firstPersonCamera = cameraSystem.createCamera(CameraType.FIRST_PERSON, {
  lookSpeed: 0.1,
  movementSpeed: 1.0,
  constraints: {
    minPolarAngle: 0,
    maxPolarAngle: Math.PI,
  }
});

// Make it the active camera
cameraSystem.setActiveCamera(CameraType.FIRST_PERSON);

// In your animation loop
function animate(time) {
  // Update the camera system (deltaTime in seconds)
  cameraSystem.update(deltaTime);
  
  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}

Camera Types

First Person Camera

First-person perspective camera with mouse/keyboard controls, ideal for FPS games.

cameraSystem.createCamera(CameraType.FIRST_PERSON, {
  lookSpeed: 0.1,
  movementSpeed: 1.0,
  constraints: {
    minPolarAngle: 0,
    maxPolarAngle: Math.PI,
  }
});

Third Person Camera

Camera that follows a target from a configurable offset, ideal for action/adventure games.

cameraSystem.createCamera(CameraType.THIRD_PERSON, {
  target: player, // THREE.Object3D to follow
  offset: new THREE.Vector3(0, 2, -5),
  lookAtOffset: new THREE.Vector3(0, 1, 0),
  damping: 0.5,
  rotationSpeed: 0.1
});

Orbit Camera

Camera that orbits around a target point, good for strategy games or inspection views.

cameraSystem.createCamera(CameraType.ORBIT, {
  target: new THREE.Vector3(0, 0, 0),
  minDistance: 2,
  maxDistance: 20,
  initialDistance: 10,
  damping: 0.2,
  rotationSpeed: 1.0
});

Top Down Camera

Bird's eye view camera, ideal for strategy or management games.

cameraSystem.createCamera(CameraType.TOP_DOWN, {
  height: 10,
  angle: Math.PI / 8, // slight angle from directly above
  target: new THREE.Vector3(0, 0, 0),
  bounds: {
    minX: -100, maxX: 100,
    minZ: -100, maxZ: 100
  }
});

Isometric Camera

Fixed-angle orthographic projection, great for isometric-style games.

cameraSystem.createCamera(CameraType.ISOMETRIC, {
  zoom: 100,
  position: new THREE.Vector3(10, 10, 10),
  target: new THREE.Vector3(0, 0, 0)
});

Side Scroller Camera

2D-style camera with options for parallax, ideal for platformers.

cameraSystem.createCamera(CameraType.SIDE_SCROLLER, {
  target: player,
  deadZone: { x: 0.1, y: 0.2 }, // percentage of screen
  bounds: {
    minX: 0, maxX: 100,
    minY: 0, maxY: 50
  },
  damping: 0.5
});

Cinematic Camera

For cutscenes and scripted camera movements.

cameraSystem.createCamera(CameraType.CINEMATIC, {
  fov: 35, // cinematic narrower FOV
  depthOfField: {
    enabled: true,
    focusDistance: 10,
    bokehStrength: 0.05
  },
  waypoints: [
    {
      position: new THREE.Vector3(0, 2, 5),
      lookAt: player.position,
      duration: 2.0,
      fov: 50
    },
    {
      position: new THREE.Vector3(5, 1, 0),
      lookAt: enemy.position,
      duration: 3.0,
      fov: 35
    }
  ]
});

// Play the sequence
cameraSystem.getCamera(CameraType.CINEMATIC).playSequence();

Camera Transitions

Smoothly transition between different camera types:

// Transition from First Person to Orbit camera over 2 seconds
cameraSystem.transitionTo(CameraType.ORBIT, {
  duration: 2.0,
  easing: 'easeInOutQuad',
  onComplete: () => console.debug('Transition complete')
});

Advanced Usage

Camera Shake

// Add camera shake to the active camera
cameraSystem.getActiveCamera().shake(0.5); // intensity between 0-1

Custom Cameras

Extend the BaseCamera class to create custom camera types:

import { BaseCamera, CameraType } from '@fred/camera-system';

class MyCustomCamera extends BaseCamera {
  constructor(cameraObject, config) {
    // Define a custom camera type
    super(cameraObject, 'CUSTOM', config);
  }
  
  // Override update method for custom behavior
  update(deltaTime) {
    // Custom update logic
  }
}

// Register and use your custom camera
cameraSystem.registerCamera('CUSTOM', MyCustomCamera);
cameraSystem.createCamera('CUSTOM', myConfig);

Documentation

For full API documentation, see the API Reference.

Examples

• First Person Controls
• Third Person Follow Camera
• Orbital Camera
• Cinematic Sequence
• Camera Transitions

License

MIT