CosmicClash/FLIGHT_MANUAL.md

# 🚀 Cosmic Clash Flight Manual

Welcome to space, pilot! This guide will teach you everything you need to know about piloting your ship in the vast cosmos.

## 🎮 Control Schemes

### Keyboard Controls

#### Translation (Movement)

- `W` - Forward Thrust (Main Engines)
- `S` - Reverse Thrust (Retro Engines)
- `A` - Strafe Left (Port Thrusters)
- `D` - Strafe Right (Starboard Thrusters)
- `E` - Thrust Up (Dorsal Thrusters)
- `Q` - Thrust Down (Ventral Thrusters)
- `Shift` - Turbo Boost (Forward Only)

#### Rotation (Attitude Control)

- `J` - Turn Left (Yaw Left)
- `L` - Turn Right (Yaw Right)
- `I` - Pitch Up (Nose Up)
- `K` - Pitch Down (Nose Down)
- `U` - Roll Left (Bank Left)
- `O` - Roll Right (Bank Right)

### Controller Controls

#### Translation

- Left Stick - Strafe (Left/Right) + Thrust (Forward/Back)
- Right Trigger - Forward Thrust
- Left Trigger - Reverse Thrust
- Face Buttons - Up/Down Thrust

#### Rotation

- Right Stick - Pitch/Yaw
- Shoulder Buttons - Roll
- `A Button` - Turbo Boost

## 🛸 Basic Flight Principles

### Understanding Your Ship

Your ship is a **realistic space vehicle** with the following characteristics:

- **Momentum Conservation**: You keep moving even when not thrusting
- **Independent Rotation**: Your ship can face any direction while moving in another
- **Thruster-Based Movement**: Different thrusters provide different amounts of force

### Thruster Systems

1. **Main Engines** (Forward/Reverse): Most powerful, used for primary acceleration
2. **Maneuvering Thrusters** (Strafe/Vertical): Less powerful, for precise positioning
3. **Attitude Control** (Rotation): Independent rotational control around all three axes

## 🎯 Flight Techniques

### Beginner Maneuvers

#### Basic Movement

1. **Forward Flight**: Hold `W` to accelerate forward
2. **Turning**: Use `J`/`L` to turn left/right while moving
3. **Stopping**: Turn around 180° and thrust forward to decelerate
4. **Hovering**: Use vertical thrusters (`E`/`Q`) to maintain altitude

#### Camera Control

- **Ball Cam**: Press `Enter` to toggle ball tracking camera
- **Ship Cam**: Normal follow camera that looks where your ship points

### Intermediate Maneuvers

#### Efficient Movement

1. **Momentum Management**: Coast when possible to conserve energy
2. **Precision Landing**: Use gentle bursts of opposing thrust
3. **Quick Turns**: Combine rotation with strafe thrusters for sharp direction changes

#### Combat Positioning

1. **Strafing**: Move sideways while keeping guns on target
2. **Evasive Maneuvers**: Unpredictable movement patterns using all thrusters

### Advanced Techniques

#### Orbital Mechanics

1. **Prograde Burn**: Thrust in direction of movement to speed up
2. **Retrograde Burn**: Thrust opposite to movement to slow down
3. **Radial Burns**: Thrust perpendicular to movement to change orbit

#### Expert Maneuvers

1. **Flip and Burn**:

   - Accelerate forward until at desired speed
   - Rotate 180° while maintaining momentum
   - Fire main engines to decelerate efficiently
   - Most fuel-efficient way to stop

2. **Translation Sliding**:

   - Build up forward momentum
   - Use strafe thrusters to "slide" sideways
   - Maintain forward velocity while moving laterally

3. **Zero-G Ballet**:
   - Combine all rotation axes for complex orientation changes
   - Use momentum to coast through tight spaces
   - Master the "six degrees of freedom"

## 🎮 Ball Cam vs Ship Cam

### Ball Cam Mode (`Enter` to toggle)

- **Camera**: Always looks toward the ball
- **Ship Control**: Based on ship orientation (NOT camera view)
- **Best For**: Tracking the ball during gameplay
- **Challenge**: Movement direction may not match what you're looking at

### Ship Cam Mode

- **Camera**: Looks where your ship is pointing
- **Ship Control**: Intuitive - forward is where you're looking
- **Best For**: Precise navigation and docking
- **Advantage**: What you see is where you'll go

## ⚡ Energy Management

### Turbo System

- **Activation**: Hold `Shift` (keyboard) or `A` (controller) while thrusting forward
- **Effect**: 2.5x thrust multiplier on main engines only
- **Strategy**: Use for quick acceleration or emergency maneuvers

### Thrust Efficiency

- **Main Engines**: Most powerful, use for primary movement
- **Maneuvering Thrusters**: Less powerful but more precise
- **Conservation**: Coast on momentum when possible

## 🏆 Mastery Tips

### "Easy to Learn, Hard to Master"

1. **Start Simple**: Learn basic forward movement and turning
2. **Add Complexity**: Gradually incorporate strafe and vertical movement
3. **Master Physics**: Understand momentum and how forces combine
4. **Think in 3D**: Space has no "up" - use all six degrees of freedom

### Skill Development Path

1. **Novice**: Can fly forward and turn
2. **Pilot**: Comfortable with all basic movements
3. **Ace**: Uses momentum and efficient maneuvering
4. **Commander**: Masters complex orbital mechanics and combat flying

### Practice Exercises

1. **Figure-8 Flying**: Practice smooth turns and momentum control
2. **Precision Landing**: Land gently on targets using minimal thrust
3. **Obstacle Course**: Navigate tight spaces using translation controls
4. **Combat Training**: Practice keeping guns on target while evading

## 🔧 Tuning Your Ship

The following parameters can be adjusted for different flight characteristics:

- **Thrust Power**: How quickly you accelerate
- **Maneuvering Thrust**: Precision vs power for side movement
- **Rotation Power**: How quickly you can turn
- **Drag Coefficients**: How much momentum you retain

## 🌌 Welcome to Space

Remember: In space, every action has an equal and opposite reaction. Master the physics, and you'll master the game. Your ship responds to real forces - there's no magic "turn toward movement" or artificial limitations.

**Fly safe, pilot. The cosmos awaits!**

---

_"The universe is not only stranger than we imagine, it is stranger than we can imagine." - But your ship controls make perfect sense once you learn them._