vibe1_delta/README.md

# ViBe1 Delta - Simulador de Sprites con Fisica

**ViBe1 Delta** es un programa de demostracion que utiliza **SDL3** para mostrar sprites (pelotas) rebotando en pantalla con simulacion de fisica basica. Este proyecto sirve como base para experimentar con bucles de juego, renderizado y fisica en tiempo real.

## 🎯 Caracteristicas Actuales

- **Simulacion de fisica**: Gravedad, rebotes y colisiones con perdida de energia
- **Multiples escenarios**: 8 configuraciones predefinidas (1 a 100,000 pelotas)
- **Interactividad**: Controles de teclado para modificar el comportamiento
- **Renderizado eficiente**: Uso de SDL3 con escalado logico
- **Colores aleatorios**: Cada pelota tiene un color unico generado proceduralmente
- **Monitor de rendimiento**: Contador FPS en tiempo real
- **Control V-Sync**: Activacion/desactivacion dinamica del V-Sync

## 🎮 Controles

| Tecla | Accion |
|-------|--------|
| `V` | **Alternar V-Sync ON/OFF** |
| `1-8` | Cambiar numero de pelotas (1, 10, 100, 500, 1K, 10K, 50K, 100K) |
| `ESPACIO` | Impulsar todas las pelotas hacia arriba |
| `G` | Alternar direccion de la gravedad |
| `ESC` | Salir del programa |

## 📊 Informacion en Pantalla

- **Esquina superior izquierda**: Estado V-Sync (VSYNC: ON/OFF) en **cian**
- **Esquina superior derecha**: Contador FPS en tiempo real en **amarillo**
- **Centro**: Numero de pelotas activas en **blanco** (temporal)

## 🏗️ Estructura del Proyecto

```
vibe_delta/
├── source/
│   ├── main.cpp        # Bucle principal y logica del juego
│   ├── ball.h/cpp      # Clase Ball - logica de las pelotas
│   ├── defines.h       # Constantes y configuracion
│   └── external/       # Utilidades y bibliotecas externas
│       ├── sprite.h/cpp    # Clase Sprite - renderizado de texturas
│       ├── texture.h/cpp   # Clase Texture - gestion de imagenes
│       ├── dbgtxt.h        # Sistema de debug para texto en pantalla
│       └── stb_image.h     # Biblioteca para cargar imagenes
├── resources/
│   └── ball.png        # Textura de la pelota (10x10 pixeles)
├── CMakeLists.txt      # Configuracion de CMake
├── Makefile           # Configuracion de Make
├── CLAUDE.md          # Seguimiento de desarrollo
└── .gitignore         # Archivos ignorados por Git
```

## 🔧 Requisitos del Sistema

- **SDL3** (Simple DirectMedia Layer 3)
- **C++20** compatible compiler
- **CMake 3.20+** o **Make**
- Plataforma: Windows, Linux, macOS

### Instalacion de SDL3

#### Windows (MinGW)
```bash
# Usando vcpkg o compilar desde fuente
vcpkg install sdl3
```

#### Linux
```bash
# Ubuntu/Debian
sudo apt install libsdl3-dev
# Arch Linux
sudo pacman -S sdl3
```

#### macOS
```bash
brew install sdl3
```

## 🚀 Compilacion

### Opcion 1: CMake (Recomendado)
```bash
mkdir build && cd build
cmake ..
make
```

### Opcion 2: Make directo
```bash
make
```

## ▶️ Ejecucion

```bash
# Desde la raiz del proyecto
./vibe1_delta        # Linux/macOS
./vibe1_delta.exe    # Windows
```

## 📊 Detalles Tecnicos

### Configuracion Actual
- **Resolucion**: 320x240 pixeles (escalado x3 = 960x720)
- **FPS objetivo**: 60 FPS (16.67ms por frame)
- **Fisica**: Gravedad constante (0.2f), rebotes con perdida de energia
- **Tamaño de pelota**: 10x10 pixeles
- **V-Sync**: Activado por defecto, controlable dinamicamente

### Arquitectura del Codigo

1. **main.cpp**: Contiene el bucle principal con tres fases:
   - `update()`: Actualiza la logica del juego + calculo FPS
   - `checkEvents()`: Procesa eventos de entrada
   - `render()`: Renderiza la escena + overlays informativos

2. **Ball**: Maneja la fisica de cada pelota individual
3. **Sprite**: Sistema de renderizado de texturas con filtro nearest neighbor
4. **Texture**: Gestion de carga y renderizado de imagenes con filtro pixel-perfect

### Problema Actual: FPS Dependiente

El sistema actual usa un **bucle acoplado** donde la logica y renderizado estan sincronizados a 60 FPS fijos:

```cpp
// En update() - linea 236
if (SDL_GetTicks() - ticks > DEMO_SPEED) { // DEMO_SPEED = 1000/60
    // Solo aqui se actualiza la fisica
}
```

## 🚧 Mejoras Planificadas

### Implementacion de Delta Time

**Objetivo**: Separar el bucle de proceso del de renderizado usando delta time para conseguir:

- **Simulacion independiente del framerate**
- **Mejor rendimiento** en escenarios de alta carga
- **Consistencia** en diferentes dispositivos
- **Preparacion para optimizaciones futuras**

### Cambios Previstos

1. **Sistema de timing basado en delta time**
2. **Bucle de juego desacoplado** (logica vs renderizado)
3. **Interpolacion** para renderizado suave
4. **Optimizaciones de rendimiento**

## 🛠️ Desarrollo

Para contribuir al proyecto:

1. Fork del repositorio
2. Crear rama de feature (`git checkout -b feature/nueva-caracteristica`)
3. Commit de cambios (`git commit -am 'Añadir nueva caracteristica'`)
4. Push a la rama (`git push origin feature/nueva-caracteristica`)
5. Crear Pull Request

## 📝 Notas Tecnicas

- El proyecto usa **smart pointers** (unique_ptr, shared_ptr) para gestion de memoria
- **RAII** para recursos SDL
- **Separacion de responsabilidades** entre clases
- **Configuracion multiplataforma** (Windows, Linux, macOS)
- **Filtro nearest neighbor** para texturas pixel-perfect
- **Sistema de metricas** en tiempo real (FPS, V-Sync)

## 🐛 Problemas Conocidos

- FPS drops significativos con >10,000 pelotas
- Timing dependiente del framerate (solucion en desarrollo)
- Sin interpolacion en el renderizado

---

*Proyecto desarrollado como base para experimentacion con game loops y fisica en tiempo real usando SDL3.*