# 🌊 WebOcean

An interactive 3D ocean simulation using **WebGPU**, TypeScript, and Perlin noise for realistic water wave generation.

![WebGPU](https://img.shields.io/badge/WebGPU-Chrome113+-990000?style=flat-square)
![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square)
![Vite](https://img.shields.io/badge/Vite-6.0-646CFF?style=flat-square)

## ✨ Features

- **Real-time Ocean Simulation** - Dynamic water surface with Perlin noise-based displacement
- **WebGPU Rendering** - Modern GPU API for optimal performance and future tessellation support
- **Advanced Rendering Techniques**:
  - Fresnel reflection for realistic water appearance
  - Subsurface scattering for light penetration
  - Specular highlights for sun glitter effect
  - Dynamic normal mapping from displacement
  - Gradient skybox with sun rendering
- **Dual Camera System**:
  - **Orbital Camera** - Rotate around the ocean surface
  - **FPS Camera** - Free-flying first-person exploration
- **Animation Controls**:
  - Pause/play ocean animation
  - Adjustable speed (1x-5x)
- **Rendering Modes**:
  - Wireframe toggle for mesh visualization
- **Responsive Design** - Automatically adapts to window size
- **Performance Monitoring** - Real-time FPS counter and frame time

## 🎮 Controls

### Camera Controls

| Action | Keys |
|--------|------|
| **Toggle Camera Mode** | `C` |
| **Reset Camera** | `R` |
| **Mouse Drag** | Click and drag to rotate camera |

### Orbital Camera Mode (Default)

| Action | Keys |
|--------|------|
| **Rotate** | `W` `A` `S` `D` or Arrow Keys |
| **Zoom In/Out** | `Q` / `E` or `+` / `-` |

### FPS Camera Mode

| Action | Keys |
|--------|------|
| **Move Forward/Back** | `W` / `S` |
| **Strafe Left/Right** | `A` / `D` |
| **Move Up/Down** | `E` / `Q` or `Space` / `Ctrl` |
| **Fast Movement** | Hold `Shift` |
| **Look Around** | Click and drag mouse |

### Rendering Controls

| Action | Keys |
|--------|------|
| **Wireframe Mode** | `F` |
| **Pause/Play Animation** | `P` |
| **Set Speed** | `0` (reset) `1` `2` `3` `4` `5` (multipliers) |
| **Toggle Help UI** | `H` |

## 🚀 Getting Started

### Prerequisites

- **Node.js** (v16 or higher)
- **Browser**: Chrome 113+, Edge 113+, or Firefox 130+ (with WebGPU enabled)
- npm or yarn

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd WebOcean

# Install dependencies
npm install
```

### Development

```bash
# Start development server with hot reload
npm run dev
```

Open your browser at `http://localhost:3000`

### Build for Production

```bash
# Build optimized production bundle
npm run build

# Preview production build
npm run preview
```

The built files will be in the `dist/` directory.

## 🛠️ Technical Details

### Architecture

- **WebGL 2.0** - Hardware-accelerated 3D graphics
- **TypeScript** - Type-safe development
- **Vite** - Fast build tool and dev server
- **gl-matrix** - High-performance matrix and vector operations

### Rendering Pipeline

1. **First Pass**: Generate Perlin noise texture for displacement
2. **Second Pass**: Render ocean grid with:
   - Vertex displacement using noise texture
   - Dynamic normal calculation
   - Advanced lighting (Fresnel + subsurface scattering)
   - Specular highlights

### Project Structure

```
WebOcean/
├── src/
│   └── main.ts          # Main application code
├── index.html           # HTML entry point
├── vite.config.ts       # Vite configuration
├── tsconfig.json        # TypeScript configuration
└── package.json         # Project dependencies
```

## 📝 Configuration

Water and rendering parameters can be modified in `src/main.ts`:

- `GRID_SIZE` - Resolution of water mesh (default: 128)
- `NOISE_TEXTURE_WIDTH/HEIGHT` - Perlin noise resolution (default: 256x256)
- `FOV` - Field of view
- `OCEAN_COLOR` - Base water color
- `MOUSE_SENSITIVITY` - Camera rotation sensitivity

## 🔧 Development Notes

### Browser Compatibility

Requires a browser with WebGL 2.0 support:
- Chrome 56+
- Firefox 51+
- Edge 79+
- Safari 15+

### Performance

- Target: 60 FPS on modern hardware
- Grid complexity affects performance linearly
- Noise texture resolution affects memory usage

## 📄 License

ISC License - see LICENSE file for details

## 👤 Author

Julian Niessner

## 🙏 Acknowledgments

- Perlin noise implementation based on [WebGL Perlin Noise tutorial](https://medium.com/neosavvy-labs/webgl-with-perlin-noise-part-1-a87b56bbc9fb)
- Fresnel and lighting techniques from various WebGL resources

---

**Enjoy exploring the digital ocean! 🌊**