@directivegames/genesys.js 3.1.24

package/docs/guides/10-camera-system.md

@@ -0,0 +1,778 @@
+## Instruction
+Use this doc to understand how the camera system works in Genesys.js and learn how the priority-based camera selection determines the active camera, how to work with Three.js cameras directly in the scene graph, and when to create cameras manually.
+
+# 10-camera-system.md
+
+## Camera System in Genesys.js
+
+The camera system in Genesys.js determines what the player sees in your game world. Understanding how cameras work, when to create them manually, and how to control their movement is essential for creating engaging gameplay experiences. This guide covers the camera component, how the world selects which camera to use for rendering, and common patterns for camera control.
+
+---
+
+## 1. How the World Picks Which Camera to Use
+
+The `World` uses a priority system to determine which camera renders the scene:
+
+1. **Override Camera**: If you've set an override camera via `world.setOverrideCamera()`, it takes highest priority.
+2. **Player Pawn Camera**: If no override camera is set, the world looks for a `THREE.Camera` object directly attached to the first player's pawn.
+3. **Fallback**: If no camera is found, an error is thrown.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Method 1: Use the default pawn camera (most common)
+        const { pawn, controller } = ENGINE.GameBuilder.createDefaultPawn(this.world);
+        // The pawn automatically has a THREE.Camera object attached that will be used for rendering
+
+        // Method 2: Create a Three.js camera and attach it to a scene component
+        const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+        const cameraActor = new ENGINE.Actor({
+            position: new THREE.Vector3(0, 10, 10)
+        });
+        cameraActor.rootComponent.add(camera);
+        this.world.addActors(cameraActor);
+
+        // Method 3: Use an override camera (for UI, cinematics, etc.)
+        const overrideCamera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+        this.world.setOverrideCamera(overrideCamera);
+    }
+}
+```
+
+---
+
+## 2. Working with Three.js Cameras
+
+In Genesys.js, you work directly with Three.js camera objects instead of wrapper components. This provides more flexibility and direct access to all Three.js camera features.
+
+### Creating Cameras
+
+Create cameras using standard Three.js constructors:
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Perspective camera (default) - for 3D games
+const perspectiveCamera = new THREE.PerspectiveCamera(
+    75,    // Field of view in degrees
+    1,     // Aspect ratio (will be automatically updated by the world)
+    0.1,   // Near clipping plane
+    1000   // Far clipping plane
+);
+
+// Orthographic camera - for 2D games or isometric views
+const orthographicCamera = new THREE.OrthographicCamera(
+    -10,   // Left
+    10,    // Right
+    10,    // Top
+    -10,   // Bottom
+    0.1,   // Near
+    1000   // Far
+);
+```
+
+### Attaching Cameras to Scene Components
+
+To integrate cameras into the scene graph for transform updates, attach them to scene components:
+
+```typescript
+const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+const cameraActor = new ENGINE.Actor({
+    position: new THREE.Vector3(0, 5, 10)
+});
+
+// Attach the camera to the actor's root component
+cameraActor.rootComponent.add(camera);
+
+// The camera will now inherit the actor's transform
+this.world.addActors(cameraActor);
+```
+
+---
+
+## 3. When to Create a Camera Manually
+
+Most of the time, you won't need to create cameras manually. The `GameBuilder` methods automatically create pawns with cameras attached. However, you should create cameras manually in these situations:
+
+### Security Cameras or Multiple Viewpoints
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class SecurityCameraGame extends ENGINE.BaseGameLoop {
+    private securityCameras: THREE.Camera[] = [];
+    private currentCameraIndex: number = 0;
+
+    protected override preStart(): void {
+        // Create multiple security cameras
+        const cameraPositions = [
+            new THREE.Vector3(10, 5, 10),
+            new THREE.Vector3(-10, 5, 10),
+            new THREE.Vector3(0, 15, 0)
+        ];
+
+        cameraPositions.forEach((position, index) => {
+            const camera = new THREE.PerspectiveCamera(60, 1, 0.1, 100);
+            const cameraActor = new ENGINE.Actor({
+                name: `SecurityCamera_${index}`,
+                position
+            });
+            
+            // Attach camera to the actor's root component
+            cameraActor.rootComponent.add(camera);
+            
+            // Make the camera look at the center of the scene
+            cameraActor.rootComponent.lookAt(0, 0, 0);
+            
+            this.world.addActors(cameraActor);
+            this.securityCameras.push(camera);
+        });
+
+        // Start with the first camera
+        this.switchToCamera(0);
+    }
+
+    private switchToCamera(index: number): void {
+        if (index >= 0 && index < this.securityCameras.length) {
+            this.world.setOverrideCamera(this.securityCameras[index]);
+            this.currentCameraIndex = index;
+        }
+    }
+}
+```
+
+### Cinematic Sequences
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class CinematicDemo extends ENGINE.BaseGameLoop {
+    private cinematicCamera: THREE.Camera | null = null;
+
+    protected override preStart(): void {
+        // Create a cinematic camera for cutscenes
+        this.cinematicCamera = new THREE.PerspectiveCamera(
+            35,    // Narrower FOV for cinematic feel
+            1,     // Aspect ratio
+            0.1,   // Near
+            1000   // Far
+        );
+
+        const cameraActor = new ENGINE.Actor({
+            name: "CinematicCamera",
+            position: new THREE.Vector3(0, 2, 5)
+        });
+
+        // Attach camera to the actor
+        cameraActor.rootComponent.add(this.cinematicCamera);
+        this.world.addActors(cameraActor);
+    }
+
+    public startCinematic(): void {
+        // Switch to cinematic camera
+        this.world.setOverrideCamera(this.cinematicCamera!);
+        
+        // Animate the camera (example using a timer)
+        this.world.timerSystem.setTimer(() => {
+            // Return to player camera after 5 seconds
+            this.world.setOverrideCamera(null); // Will fall back to player pawn camera
+        }, 5000);
+    }
+}
+```
+
+### Top-Down or Isometric Games
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class TopDownGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Create a fixed top-down camera
+        const camera = new THREE.OrthographicCamera(-15, 15, 15, -15, 0.1, 1000);
+        
+        const topDownCameraActor = new ENGINE.Actor({
+            position: new THREE.Vector3(0, 20, 0),
+            rotation: new THREE.Euler(-Math.PI / 2, 0, 0) // Look straight down
+        });
+
+        // Attach camera to the actor
+        topDownCameraActor.rootComponent.add(camera);
+        this.world.addActors(topDownCameraActor);
+        
+        // Set this as the override camera
+        this.world.setOverrideCamera(camera);
+
+        // Create a player without a camera (since we're using the fixed camera)
+        const player = new ENGINE.Pawn({
+            position: new THREE.Vector3(0, 0, 0),
+            movementComponent: new ENGINE.TopDownMovementComponent(),
+            camera: null // No camera on the pawn
+        });
+
+        const controller = new ENGINE.PlayerController();
+        controller.possess(player);
+        this.world.addActors(player, controller);
+    }
+}
+```
+
+---
+
+## 4. Patterns for Camera Movement Control
+
+When you need to control camera movement or transform, here are the most common patterns:
+
+### Pattern 1: Indirect Control via Pawn Movement Behavior
+
+One of the most common and effective ways to control camera movement is indirectly through the pawn's movement component. Since cameras are typically attached to pawns, customizing how the pawn moves and rotates directly affects the camera experience.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+@ENGINE.GameClass()
+class CustomCharacterMovement extends ENGINE.CharacterMovementComponent {
+    private headBobAmount: number = 0.02;
+    private headBobSpeed: number = 10;
+    private headBobTime: number = 0;
+    private cameraShakeIntensity: number = 0;
+    private cameraShakeDecay: number = 5;
+
+    public override tickPrePhysics(deltaTime: number): void {
+        super.tickPrePhysics(deltaTime);
+
+        const owner = this.getActor()!;
+        const camera = owner.getComponent(THREE.Camera);
+        
+        if (camera && this.options.movementType === ENGINE.CharacterMovementType.FirstPerson) {
+            this.applyHeadBob(camera, deltaTime);
+            this.applyCameraShake(camera, deltaTime);
+        }
+    }
+
+    private applyHeadBob(camera: THREE.Camera, deltaTime: number): void {
+        // Only apply head bob when moving
+        const isMoving = Math.abs(this.forwardInput) > 0.1 || Math.abs(this.rightInput) > 0.1;
+        
+        if (isMoving) {
+            this.headBobTime += deltaTime * this.headBobSpeed;
+            const bobOffset = Math.sin(this.headBobTime) * this.headBobAmount;
+            
+            // Apply vertical head bob
+            camera.position.y = 0 + bobOffset;
+            
+            // Optional: Add slight horizontal sway
+            const swayOffset = Math.cos(this.headBobTime * 0.5) * this.headBobAmount * 0.5;
+            camera.position.x = swayOffset;
+        } else {
+            // Smoothly return to center when not moving
+            camera.position.y = THREE.MathUtils.lerp(camera.position.y, 0, deltaTime * 5);
+            camera.position.x = THREE.MathUtils.lerp(camera.position.x, 0, deltaTime * 5);
+        }
+    }
+
+    private applyCameraShake(camera: THREE.Camera, deltaTime: number): void {
+        if (this.cameraShakeIntensity > 0) {
+            // Apply random shake
+            const shakeX = (Math.random() - 0.5) * this.cameraShakeIntensity;
+            const shakeY = (Math.random() - 0.5) * this.cameraShakeIntensity;
+            const shakeZ = (Math.random() - 0.5) * this.cameraShakeIntensity;
+            
+            camera.position.add(new THREE.Vector3(shakeX, shakeY, shakeZ));
+            
+            // Decay the shake over time
+            this.cameraShakeIntensity = Math.max(0, this.cameraShakeIntensity - this.cameraShakeDecay * deltaTime);
+        }
+    }
+
+    // Public method to trigger camera shake from external events
+    public addCameraShake(intensity: number): void {
+        this.cameraShakeIntensity = Math.max(this.cameraShakeIntensity, intensity);
+    }
+}
+
+class IndirectCameraControlDemo extends ENGINE.BaseGameLoop {
+    private player: ENGINE.Pawn | null = null;
+
+    protected override preStart(): void {
+        // Create a pawn with custom movement that affects camera behavior
+        const customMovement = new CustomCharacterMovement({
+            ...ENGINE.CharacterMovementComponent.DEFAULT_OPTIONS,
+            movementType: ENGINE.CharacterMovementType.FirstPerson,
+            maxSpeed: 15,
+            lookRightSpeed: 0.003, // Slower look speed for more precise aiming
+            lookUpSpeed: 0.003
+        });
+
+        const camera = new THREE.PerspectiveCamera(90, 1, 0.01, 1000); // Wider FOV for more immersive feel
+        
+        this.player = new ENGINE.Pawn({
+            position: new THREE.Vector3(0, 2, 0),
+            movementComponent: customMovement,
+            camera: camera
+        });
+
+        const controller = new ENGINE.PlayerController();
+        controller.possess(this.player);
+        this.world.addActors(this.player, controller);
+
+        // Set up some test objects to interact with
+        this.createTestEnvironment();
+        
+        // Set up input for camera shake testing
+        this.world.inputManager.onKeyDown.add(this.handleSpecialInput.bind(this));
+    }
+
+    private handleSpecialInput(event: KeyboardEvent): boolean {
+        if (event.code === 'KeyX' && this.player) {
+            // Trigger camera shake when X is pressed
+            const movement = this.player.movementComponent as CustomCharacterMovement;
+            movement.addCameraShake(0.1);
+            return true;
+        }
+        return false;
+    }
+
+    private createTestEnvironment(): void {
+        // Add some objects to make movement more interesting
+        ENGINE.GameBuilder.createDefaultLighting(this.world);
+        ENGINE.GameBuilder.createDefaultGround(this.world);
+        
+        // Add some boxes to walk around
+        for (let i = 0; i < 5; i++) {
+            this.world.addBox({
+                position: new THREE.Vector3(
+                    (Math.random() - 0.5) * 20,
+                    1,
+                    (Math.random() - 0.5) * 20
+                ),
+                width: 2,
+                height: 2,
+                depth: 2,
+                color: ENGINE.Color.BLUE
+            });
+        }
+    }
+}
+```
+
+### Pattern 2: Third-Person Camera Behavior via Movement Component
+
+For third-person games, you can customize camera behavior by modifying how the movement component handles camera positioning and rotation.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+@ENGINE.GameClass()
+class CustomThirdPersonMovement extends ENGINE.CharacterMovementComponent {
+    private cameraDistance: number = 8;
+    private cameraHeight: number = 3;
+    private cameraCollisionRadius: number = 0.5;
+
+    constructor(options: ENGINE.CharacterMovementOptions) {
+        super({
+            ...options,
+            movementType: ENGINE.CharacterMovementType.ThirdPerson
+        });
+    }
+
+    public override tickPrePhysics(deltaTime: number): void {
+        super.tickPrePhysics(deltaTime);
+
+        const owner = this.getActor()!;
+        const camera = owner.getComponent(THREE.Camera);
+        
+        if (camera) {
+            this.updateThirdPersonCamera(camera, deltaTime);
+        }
+    }
+
+    private updateThirdPersonCamera(camera: THREE.Camera, deltaTime: number): void {
+        // Get the desired camera position based on player rotation
+        const owner = this.getActor()!;
+        const playerRotation = owner.rootComponent.rotation.y;
+        
+        // Calculate ideal camera position
+        const idealCameraPos = new THREE.Vector3(
+            Math.sin(playerRotation) * this.cameraDistance,
+            this.cameraHeight,
+            Math.cos(playerRotation) * this.cameraDistance
+        );
+
+        // Check for obstacles between player and camera
+        const adjustedCameraPos = this.checkCameraCollision(idealCameraPos);
+        
+        // Smoothly move camera to the adjusted position
+        camera.position.lerp(adjustedCameraPos, deltaTime * 5);
+        
+        // Always look at the player (with slight upward offset)
+        const lookAtTarget = new THREE.Vector3(0, 1, 0);
+        camera.lookAt(lookAtTarget);
+    }
+
+    private checkCameraCollision(idealPos: THREE.Vector3): THREE.Vector3 {
+        const owner = this.getActor()!;
+        const world = owner.getWorld()!;
+        const playerPos = new THREE.Vector3();
+        owner.rootComponent.getWorldPosition(playerPos);
+        
+        // Simple raycast from player to ideal camera position
+        const direction = idealPos.clone().normalize();
+        const maxDistance = idealPos.length();
+        
+        // This is a simplified collision check - in a real game you'd use the physics engine
+        // For now, we'll just return the ideal position
+        return idealPos;
+    }
+
+    // Public methods to adjust camera behavior
+    public setCameraDistance(distance: number): void {
+        this.cameraDistance = Math.max(2, Math.min(20, distance));
+    }
+
+    public setCameraHeight(height: number): void {
+        this.cameraHeight = Math.max(0.5, Math.min(10, height));
+    }
+}
+
+class ThirdPersonCameraDemo extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        const customMovement = new CustomThirdPersonMovement({
+            ...ENGINE.CharacterMovementComponent.DEFAULT_OPTIONS,
+            maxSpeed: 12,
+            lookRightSpeed: 0.05,
+            lookUpSpeed: 0.03
+        });
+
+        const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+        
+        const player = new ENGINE.Pawn({
+            position: new THREE.Vector3(0, 1, 0),
+            movementComponent: customMovement,
+            camera: camera,
+            rootComponent: new ENGINE.MeshComponent({
+                geometry: ENGINE.GameBuilder.createDefaultPawnCapsuleGeometry(),
+                material: new THREE.MeshStandardMaterial({ color: ENGINE.Color.GREEN })
+            })
+        });
+
+        const controller = new ENGINE.PlayerController();
+        controller.possess(player);
+        this.world.addActors(player, controller);
+
+        // Set up environment
+        ENGINE.GameBuilder.createDefaultLighting(this.world);
+        ENGINE.GameBuilder.createDefaultGround(this.world);
+        
+        // Add input for camera distance adjustment
+        this.world.inputManager.onKeyDown.add((event) => {
+            const movement = player.movementComponent as CustomThirdPersonMovement;
+            if (event.code === 'Equal') { // Plus key
+                movement.setCameraDistance(8); // Reset to default
+                return true;
+            } else if (event.code === 'Minus') {
+                movement.setCameraDistance(4); // Closer camera
+                return true;
+            }
+            return false;
+        });
+    }
+}
+```
+
+### Pattern 3: Follow Component for Smooth Automated Following
+
+The `ENGINE.FollowComponent` provides automated smooth following behavior with configurable damping and offsets. This isn't manual control - it's an automated system that creates smooth camera movement without requiring you to write movement logic.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class FollowCameraDemo extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Create a target to follow (like a vehicle or character)
+        const target = new ENGINE.Actor({
+            position: new THREE.Vector3(0, 0, 0),
+            rootComponent: new ENGINE.MeshComponent({
+                geometry: new THREE.BoxGeometry(2, 1, 4),
+                material: new THREE.MeshStandardMaterial({ color: 'red' })
+            })
+        });
+
+        // Create a camera that follows the target
+        const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+        
+        const followCamera = new ENGINE.FollowComponent({
+            target: target.rootComponent,
+            positionDamping: 0.05,              // Smooth following (0 = no follow, 1 = instant)
+            useCameraLookAtConvention: true,    // Camera looks at target
+            positionOffset: new THREE.Vector3(0, 5, -10), // Camera position relative to target
+            lookAtOffset: new THREE.Vector3(0, 1, 0)      // Point to look at on target
+        });
+
+        // Attach the camera to the follow component
+        followCamera.add(camera);
+
+        // Add the follow camera to the target so it moves with it
+        target.rootComponent.add(followCamera);
+
+        this.world.addActors(target);
+        
+        // Set the camera as the override camera
+        this.world.setOverrideCamera(camera);
+    }
+}
+```
+
+### Pattern 4: Direct Transform Manipulation
+
+For precise control or scripted camera movements, you can directly manipulate the camera's transform.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class ScriptedCameraDemo extends ENGINE.BaseGameLoop {
+    private camera: THREE.Camera | null = null;
+    private cameraActor: ENGINE.Actor | null = null;
+    private cameraStartTime: number = 0;
+
+    protected override preStart(): void {
+        // Create a camera for scripted movement
+        this.camera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+        
+        this.cameraActor = new ENGINE.Actor({
+            position: new THREE.Vector3(0, 5, 10)
+        });
+
+        // Attach camera to the actor
+        this.cameraActor.rootComponent.add(this.camera);
+        this.world.addActors(this.cameraActor);
+        this.world.setOverrideCamera(this.camera);
+        
+        this.cameraStartTime = this.world.getGameTime();
+    }
+
+    protected override tick(deltaTime: number): void {
+        super.tick(deltaTime);
+
+        if (this.cameraActor) {
+            const elapsedTime = this.world.getGameTime() - this.cameraStartTime;
+            
+            // Circular camera movement
+            const radius = 15;
+            const speed = 0.5;
+            const x = Math.cos(elapsedTime * speed) * radius;
+            const z = Math.sin(elapsedTime * speed) * radius;
+            const y = 5 + Math.sin(elapsedTime * speed * 2) * 2; // Bobbing motion
+            
+            this.cameraActor.rootComponent.setWorldPosition(new THREE.Vector3(x, y, z));
+            this.cameraActor.rootComponent.lookAt(0, 0, 0); // Always look at center
+        }
+    }
+}
+```
+
+### Pattern 5: Input-Driven Camera Control
+
+Create custom camera controls that respond to player input.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+@ENGINE.GameClass()
+class FreeCameraComponent extends ENGINE.Component<ENGINE.ComponentOptions> {
+    private moveSpeed: number = 10;
+    private lookSpeed: number = 0.002;
+    private camera: THREE.Camera | null = null;
+
+    public override beginPlay(): void {
+        super.beginPlay();
+        
+        // Find the camera on this actor
+        this.camera = this.getActor()?.getComponent(THREE.Camera) ?? null;
+        
+        // Set up input handlers
+        const world = this.getActor()?.getWorld();
+        if (world) {
+            world.inputManager.onMouseMove.add(this.handleMouseMove.bind(this));
+            world.inputManager.onKeyDown.add(this.handleKeyDown.bind(this));
+        }
+    }
+
+    private handleMouseMove(event: MouseEvent): boolean {
+        if (!this.camera) return false;
+
+        const deltaX = event.movementX * this.lookSpeed;
+        const deltaY = event.movementY * this.lookSpeed;
+
+        // Rotate the camera based on mouse movement
+        const rootComponent = this.getActor()!.rootComponent;
+        rootComponent.rotation.y -= deltaX; // Yaw
+        rootComponent.rotation.x -= deltaY; // Pitch
+        
+        // Clamp pitch to prevent over-rotation
+        rootComponent.rotation.x = THREE.MathUtils.clamp(
+            rootComponent.rotation.x, 
+            -Math.PI / 2, 
+            Math.PI / 2
+        );
+
+        return true; // Consume the event
+    }
+
+    private handleKeyDown(event: KeyboardEvent): boolean {
+        if (!this.camera) return false;
+
+        const rootComponent = this.getActor()!.rootComponent;
+        const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(rootComponent.quaternion);
+        const right = new THREE.Vector3(1, 0, 0).applyQuaternion(rootComponent.quaternion);
+        const up = new THREE.Vector3(0, 1, 0);
+
+        let movement = new THREE.Vector3();
+
+        switch (event.code) {
+            case 'KeyW': movement.add(forward); break;
+            case 'KeyS': movement.sub(forward); break;
+            case 'KeyA': movement.sub(right); break;
+            case 'KeyD': movement.add(right); break;
+            case 'KeyQ': movement.sub(up); break;
+            case 'KeyE': movement.add(up); break;
+            default: return false;
+        }
+
+        movement.normalize().multiplyScalar(this.moveSpeed * 0.016); // Assume 60 FPS
+        rootComponent.position.add(movement);
+
+        return true;
+    }
+}
+
+class FreeCameraDemo extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Create a free-flying camera
+        const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+        
+        const freeCamera = new ENGINE.Actor({
+            position: new THREE.Vector3(0, 5, 10),
+            components: [new FreeCameraComponent({})]
+        });
+
+        // Attach camera to the actor
+        freeCamera.rootComponent.add(camera);
+        this.world.addActors(freeCamera);
+        this.world.setOverrideCamera(camera);
+    }
+}
+```
+
+### Pattern 6: Camera Switching System
+
+For games that need multiple camera modes, create a system to switch between them.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+enum CameraMode {
+    FirstPerson,
+    ThirdPerson,
+    Cinematic
+}
+
+class MultiCameraDemo extends ENGINE.BaseGameLoop {
+    private player: ENGINE.Pawn | null = null;
+    private thirdPersonCamera: THREE.Camera | null = null;
+    private cinematicCamera: THREE.Camera | null = null;
+    private currentMode: CameraMode = CameraMode.FirstPerson;
+
+    protected override preStart(): void {
+        // Create player with first-person camera
+        const { pawn } = ENGINE.GameBuilder.createDefaultPawnWithPhysics(
+            this.world, 
+            ENGINE.CharacterMovementType.FirstPerson
+        );
+        this.player = pawn;
+
+        // Create third-person follow camera
+        this.thirdPersonCamera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+        
+        const followComponent = new ENGINE.FollowComponent({
+            target: pawn.rootComponent,
+            positionDamping: 0.1,
+            positionOffset: new THREE.Vector3(0, 2, 5),
+            useCameraLookAtConvention: true
+        });
+        followComponent.add(this.thirdPersonCamera);
+        pawn.rootComponent.add(followComponent);
+
+        // Create cinematic camera
+        this.cinematicCamera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+        const cinematicActor = new ENGINE.Actor({
+            position: new THREE.Vector3(10, 10, 10)
+        });
+        cinematicActor.rootComponent.add(this.cinematicCamera);
+        cinematicActor.rootComponent.lookAt(0, 0, 0);
+        this.world.addActors(cinematicActor);
+
+        // Set up camera switching input
+        this.world.inputManager.onKeyDown.add(this.handleCameraSwitch.bind(this));
+    }
+
+    private handleCameraSwitch(event: KeyboardEvent): boolean {
+        if (event.code === 'KeyC') {
+            this.switchCameraMode();
+            return true;
+        }
+        return false;
+    }
+
+    private switchCameraMode(): void {
+        // Cycle through camera modes
+        this.currentMode = (this.currentMode + 1) % 3;
+
+        switch (this.currentMode) {
+            case CameraMode.FirstPerson:
+                // Use the player's built-in camera
+                this.world.setOverrideCamera(null); // Falls back to player pawn camera
+                console.log("Switched to First Person");
+                break;
+
+            case CameraMode.ThirdPerson:
+                // Use the third-person follow camera
+                this.world.setOverrideCamera(this.thirdPersonCamera!);
+                console.log("Switched to Third Person");
+                break;
+
+            case CameraMode.Cinematic:
+                this.world.setOverrideCamera(this.cinematicCamera!);
+                console.log("Switched to Cinematic");
+                break;
+        }
+    }
+}
+```
+
+---
+
+## Summary
+
+The camera system in Genesys.js provides flexible options for controlling what players see:
+
+*   **Automatic Selection**: The world automatically picks the best available camera using a priority system.
+*   **Direct Three.js Integration**: Work directly with Three.js cameras for maximum flexibility and access to all features.
+*   **Scene Graph Integration**: Attach cameras to scene components to inherit transform updates automatically.
+*   **Override System**: Use `setOverrideCamera()` for UI views, cinematics, or temporary camera switches.
+*   **Control Patterns**: Use `FollowComponent` for automated smooth following, direct manipulation for scripted sequences, custom input handling for free cameras, or modify pawn movement behavior for integrated camera effects.
+
+Most games will work perfectly with the default pawn cameras created by `GameBuilder`. Only create manual cameras when you need specialized behaviors or multiple viewpoints in your game. 
+
+## Source Code
+Below are relevant engine source code you MUST digest in order to get complete understanding of the topic. Read them carefully.
+
+```
+<file path={src/game/World.ts}>
+<file path={src/actors/Pawn.ts}>
+<file path={src/actors/PlayerController.ts}>
+<file path={src/components/FollowComponent.ts}>
+<file path={src/game/GameBuilder.ts}>
+```