vibe1_delta/README.md

# ViBe1 Delta - Simulador de Sprites con Física

**ViBe1 Delta** es un programa de demostración que utiliza **SDL3** para mostrar sprites (pelotas) rebotando en pantalla con simulación de física básica. Este proyecto sirve como base para experimentar con bucles de juego, renderizado y física en tiempo real.

## <¯ Características Actuales

- **Simulación de física**: Gravedad, rebotes y colisiones con pérdida de energía
- **Múltiples escenarios**: 8 configuraciones predefinidas (1 a 100,000 pelotas)
- **Interactividad**: Controles de teclado para modificar el comportamiento
- **Renderizado eficiente**: Uso de SDL3 con escalado lógico
- **Colores aleatorios**: Cada pelota tiene un color único generado proceduralmente

## <® Controles

| Tecla | Acción |
|-------|--------|
| `1-8` | Cambiar número de pelotas (1, 10, 100, 500, 1K, 10K, 50K, 100K) |
| `ESPACIO` | Impulsar todas las pelotas hacia arriba |
| `G` | Alternar dirección de la gravedad |
| `ESC` | Salir del programa |

## <× Estructura del Proyecto

```
vibe_delta/
 source/
    main.cpp        # Bucle principal y lógica del juego
    ball.h/cpp      # Clase Ball - lógica de las pelotas
    sprite.h/cpp    # Clase Sprite - renderizado de texturas
    texture.h/cpp   # Clase Texture - gestión de imágenes
    defines.h       # Constantes y configuración
    dbgtxt.h        # Sistema de debug para texto en pantalla
    stb_image.h     # Biblioteca para cargar imágenes
 resources/
    ball.png        # Textura de la pelota (8x8 píxeles)
 CMakeLists.txt      # Configuración de CMake
 Makefile           # Configuración de Make
 .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

### Instalación 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
```

## =€ Compilación

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

### Opción 2: Make directo
```bash
make
```

## ¶ Ejecución

```bash
# Desde la raíz del proyecto
./vibe1_delta        # Linux/macOS
./vibe1_delta.exe    # Windows
```

## =Ê Detalles Técnicos

### Configuración Actual
- **Resolución**: 320x240 píxeles (escalado x3 = 960x720)
- **FPS objetivo**: 60 FPS (16.67ms por frame)
- **Física**: Gravedad constante (0.2f), rebotes con pérdida de energía
- **Tamaño de pelota**: 8x8 píxeles

### Arquitectura del Código

1. **main.cpp**: Contiene el bucle principal con tres fases:
   - `update()`: Actualiza la lógica del juego
   - `checkEvents()`: Procesa eventos de entrada
   - `render()`: Renderiza la escena

2. **Ball**: Maneja la física de cada pelota individual
3. **Sprite**: Sistema de renderizado de texturas
4. **Texture**: Gestión de carga y renderizado de imágenes

### Problema Actual: FPS Dependiente

El sistema actual usa un **bucle acoplado** donde la lógica y renderizado están sincronizados a 60 FPS fijos:

```cpp
// En update() - línea 219
if (SDL_GetTicks() - ticks > DEMO_SPEED) { // DEMO_SPEED = 1000/60
    // Actualizar lógica del juego
}
```

## =§ Mejoras Planificadas

### Implementación de Delta Time

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

- **Simulación independiente del framerate**
- **Mejor rendimiento** en escenarios de alta carga
- **Consistencia** en diferentes dispositivos
- **Preparación para optimizaciones futuras**

### Cambios Previstos

1. **Sistema de timing basado en delta time**
2. **Bucle de juego desacoplado** (lógica vs renderizado)
3. **Interpolación** 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 característica'`)
4. Push a la rama (`git push origin feature/nueva-caracteristica`)
5. Crear Pull Request

## =Ý Notas Técnicas

- El proyecto usa **smart pointers** (unique_ptr, shared_ptr) para gestión de memoria
- **RAII** para recursos SDL
- **Separación de responsabilidades** entre clases
- **Configuración multiplataforma** (Windows, Linux, macOS)

## = Problemas Conocidos

- FPS drops significativos con >10,000 pelotas
- Timing dependiente del framerate
- Sin interpolación en el renderizado

---

*Proyecto desarrollado como base para experimentación con game loops y física en tiempo real usando SDL3.*