vibe3-physics/CLAUDE.md

# Claude Code Session - ViBe3 Physics

## Estado del Proyecto

**Proyecto:** ViBe3 Physics - Simulador de sprites con físicas avanzadas
**Objetivo:** Implementar nuevas físicas experimentales expandiendo sobre el sistema de delta time
**Base:** Migrado desde vibe1_delta con sistema delta time ya implementado

## Progreso Actual

### ✅ Completado

#### 1. **Migración y Setup Inicial**
   - ✅ Renombrado vibe1_delta → vibe3_physics en todos los archivos
   - ✅ Carpeta resources → data
   - ✅ Actualizado CMakeLists.txt, .gitignore, defines.h, README.md
   - ✅ Añadido .claude/ al .gitignore
   - ✅ Sistema de compilación CMake funcionando

#### 2. **Sistema de Físicas Base (Heredado)**
   - ✅ **Delta time implementado** - Física independiente del framerate
   - ✅ Contador FPS en tiempo real (esquina superior derecha, amarillo)
   - ✅ Control V-Sync dinámico con tecla "V" (ON/OFF)
   - ✅ Display V-Sync (esquina superior izquierda, cian)
   - ✅ **Sistema de temas visuales** - 4 temas (SUNSET/OCEAN/NEON/FOREST)
   - ✅ **Batch rendering optimizado** - Maneja hasta 100,000 sprites

#### 3. **NUEVA CARACTERÍSTICA: Gravedad Direccional** 🎯
   - ✅ **Enum GravityDirection** (UP/DOWN/LEFT/RIGHT) en defines.h
   - ✅ **Ball class actualizada** para física multi-direccional
   - ✅ **Detección de superficie inteligente** - Adaptada a cada dirección
   - ✅ **Fricción direccional** - Se aplica en la superficie correcta
   - ✅ **Controles de cursor** - Cambio dinámico de gravedad
   - ✅ **Debug display actualizado** - Muestra dirección actual

#### 4. **NUEVA CARACTERÍSTICA: Coeficientes de Rebote Variables** ⚡
   - ✅ **Rango ampliado** - De 0.60-0.89 a 0.30-0.95 (+120% variabilidad)
   - ✅ **Comportamientos diversos** - Desde pelotas super rebotonas a muy amortiguadas
   - ✅ **Debug display** - Muestra coeficiente LOSS de primera pelota
   - ✅ **Física realista** - Elimina sincronización entre pelotas

### 📋 Controles Actuales

| Tecla | Acción |
|-------|--------|
| **↑** | **Gravedad hacia ARRIBA** |
| **↓** | **Gravedad hacia ABAJO** |
| **←** | **Gravedad hacia IZQUIERDA** |
| **→** | **Gravedad hacia DERECHA** |
| V | Alternar V-Sync ON/OFF |
| H | **Toggle debug display (FPS, V-Sync, física, gravedad)** |
| F1-F4 | Selección directa de tema (Atardecer/Océano/Neón/Bosque) |
| T | Ciclar entre temas de colores |
| 1-8 | Cambiar número de pelotas (1 a 100,000) |
| ESPACIO | Impulsar pelotas hacia arriba |
| G | Alternar gravedad ON/OFF (mantiene dirección) |
| ESC | Salir |

### 🎯 Debug Display (Tecla H)

Cuando está activado muestra:
```
FPS: 75           # Esquina superior derecha (amarillo)
VSYNC ON          # Esquina superior izquierda (cian)
GRAV 720          # Magnitud gravedad (magenta)
VY -145           # Velocidad Y primera pelota (magenta)
SURFACE YES       # En superficie (magenta)
LOSS 0.73         # Coeficiente rebote primera pelota (magenta)
GRAVITY DOWN      # Dirección actual (amarillo)
THEME SUNSET      # Tema activo (amarillo claro)
```

## Arquitectura Actual

```
vibe3_physics/
├── source/
│   ├── main.cpp           # Bucle principal + controles + debug
│   ├── ball.h/.cpp        # Clase Ball con física direccional
│   ├── defines.h          # Constantes + enum GravityDirection
│   └── external/          # Utilidades externas
│       ├── texture.h/.cpp # Gestión texturas + nearest filter
│       ├── sprite.h/.cpp  # Sistema sprites
│       ├── dbgtxt.h       # Debug text + nearest filter
│       └── stb_image.h    # Carga imágenes
├── data/                  # Recursos (antes resources/)
│   └── ball.png          # Textura pelota 10x10px
├── CMakeLists.txt        # Build system
└── CLAUDE.md            # Este archivo de seguimiento
```

## Sistema de Gravedad Direccional

### 🔧 Implementación Técnica

#### Enum y Estados
```cpp
enum class GravityDirection {
    DOWN,    // ↓ Gravedad hacia abajo (por defecto)
    UP,      // ↑ Gravedad hacia arriba
    LEFT,    // ← Gravedad hacia la izquierda
    RIGHT    // → Gravedad hacia la derecha
};
```

#### Lógica de Física por Dirección
- **DOWN**: Pelotas caen hacia abajo, fricción en suelo inferior
- **UP**: Pelotas "caen" hacia arriba, fricción en techo
- **LEFT**: Pelotas "caen" hacia izquierda, fricción en pared izquierda
- **RIGHT**: Pelotas "caen" hacia derecha, fricción en pared derecha

#### Cambios en Ball Class
- `on_floor_` → `on_surface_` (más genérico)
- `gravity_direction_` (nuevo miembro)
- `setGravityDirection()` (nueva función)
- `update()` completamente reescrito para lógica direccional

## Lecciones Aprendidas de ViBe2 Modules

### ✅ Éxitos de Modularización
- **C++20 modules** son viables para código propio
- **CMake + Ninja** funciona bien para modules
- **Separación clara** de responsabilidades mejora arquitectura

### ❌ Limitaciones Encontradas
- **SDL3 + modules** generan conflictos irresolubles
- **Bibliotecas externas** requieren includes tradicionales
- **Enfoque híbrido** (modules propios + includes externos) es más práctico

### 🎯 Decisión para ViBe3 Physics
- **Headers tradicionales** (.h/.cpp) por compatibilidad
- **Enfoque en características** antes que arquitectura
- **Organización por clases** en lugar de modules inicialmente

## Sistema de Coeficientes de Rebote Variables

### 🔧 Implementación Técnica

#### Problema Anterior
```cpp
// Sistema ANTIGUO - Poca variabilidad
loss_ = ((rand() % 30) * 0.01f) + 0.6f;  // 0.60 - 0.89 (diferencia: 0.29)
```

**Resultado**: Pelotas con comportamientos muy similares → Sincronización visible

#### Solución Implementada
```cpp
// Sistema NUEVO - Alta variabilidad
loss_ = ((rand() % 66) * 0.01f) + 0.30f;  // 0.30 - 0.95 (diferencia: 0.65)
```

### 🎯 Tipos de Comportamiento

#### Categorías de Materiales
- **🏀 Super Rebotona** (0.85-0.95): Casi no pierde energía, rebota muchas veces
- **⚽ Normal** (0.65-0.85): Comportamiento estándar equilibrado
- **🎾 Amortiguada** (0.45-0.65): Pierde energía moderada, se estabiliza
- **🏐 Muy Amortiguada** (0.30-0.45): Se para rápidamente, pocas rebotes

### ✅ Beneficios Conseguidos
- **+120% variabilidad** en coeficientes de rebote
- **Eliminación de sincronización** entre pelotas
- **Comportamientos diversos** visibles inmediatamente
- **Física más realista** con materiales diferentes
- **Debug display** para monitoreo en tiempo real

## 🚀 Próximos Pasos - Físicas Avanzadas

### Ideas Pendientes de Implementación

#### 1. **Colisiones Entre Partículas**
- Detección de colisión ball-to-ball
- Física de rebotes entre pelotas
- Conservación de momentum

#### 2. **Materiales y Propiedades**
- Diferentes coeficientes de rebote por pelota
- Fricción variable por material
- Densidad y masa como propiedades

#### 3. **Fuerzas Externas**
- **Viento** - Fuerza horizontal constante
- **Campos magnéticos** - Atracción/repulsión a puntos
- **Turbulencia** - Fuerzas aleatorias localizadas

#### 4. **Interactividad Avanzada**
- Click para aplicar fuerzas puntuales
- Arrastrar para crear campos de fuerza
- Herramientas de "pincel" de física

#### 5. **Visualización Avanzada**
- **Trails** - Estelas de movimiento
- **Heatmaps** - Visualización de velocidad/energía
- **Vectores de fuerza** - Visualizar gravedad y fuerzas

#### 6. **Optimizaciones**
- Spatial partitioning para colisiones
- Level-of-detail para muchas partículas
- GPU compute shaders para física masiva

### 🎮 Controles Futuros Sugeridos
```
Mouse Click:     Aplicar fuerza puntual
Mouse Drag:      Crear campo de fuerza
Mouse Wheel:     Ajustar intensidad
R:               Reset todas las pelotas
P:               Pausa/Resume física
M:               Modo materiales
W:               Toggle viento
```

## Métricas del Proyecto

### ✅ Logros Actuales
- **Compilación exitosa** con CMake
- **Commit inicial** creado (dec8d43)
- **17 archivos** versionados
- **9,767 líneas** de código
- **Física direccional** 100% funcional
- **Coeficientes variables** implementados

### 🎯 Objetivos Cumplidos
- ✅ Migración limpia desde vibe1_delta
- ✅ Sistema de gravedad direccional implementado
- ✅ Coeficientes de rebote variables (+120% diversidad)
- ✅ Debug display completo y funcional
- ✅ Controles intuitivos con teclas de cursor
- ✅ Eliminación de sincronización entre pelotas

---

## Comandos Útiles

### Compilación
```bash
mkdir -p build && cd build && cmake .. && cmake --build .
```

### Ejecución
```bash
./vibe3_physics.exe    # Windows
./vibe3_physics        # Linux/macOS
```

### Git
```bash
git status             # Ver cambios
git add .              # Añadir archivos
git commit -m "..."    # Crear commit
```

---

*Archivo de seguimiento para sesiones Claude Code - ViBe3 Physics*
*Actualizado: Implementación de gravedad direccional completada*