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

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

// 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

// 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

mkdir -p build && cd build && cmake .. && cmake --build .

Ejecución

./vibe3_physics.exe    # Windows
./vibe3_physics        # Linux/macOS

Git

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