# ViBe3 Physics - Simulador de Sprites con Física Avanzada

**ViBe3 Physics** es una demo experimental de **vibe-coding** que implementa **físicas avanzadas** con sistema de delta time independiente del framerate. Utiliza **SDL3** para renderizado optimizado con batch geometry de hasta 50,000 sprites simultáneos.

![ViBe3 Physics - Gameplay](https://php.sustancia.synology.me/images/vibe3_physics/captura_vibe3_physics_1.png)

El nombre refleja su propósito: **ViBe** (vibe-coding experimental) + **Physics** (nuevas físicas experimentales). La demo sirve como sandbox para probar bucles de juego con timing independiente, comportamientos emergentes (boids), figuras 3D procedurales y efectos demoscene.

---

## 🎯 Características Principales

- **Sistema delta time**: Física independiente del framerate (60Hz, 75Hz, 144Hz+)
- **Batch rendering**: Hasta 100,000 sprites con SDL_RenderGeometry
- **15 temas visuales**: 9 estáticos + 6 dinámicos animados (sistema de 2 páginas)
- **9 figuras 3D**: Esfera, Cubo, Helix, Torus, Cylinder, Icosahedron, Atom, Lissajous, PNG_SHAPE
- **Modo BOIDS**: Comportamiento de enjambre emergente (separación, alineación, cohesión)
- **Gravedad multidireccional**: UP/DOWN/LEFT/RIGHT con detección de superficie inteligente
- **4 modos de aplicación**: SANDBOX (manual), DEMO (auto completo), DEMO_LITE (auto física), LOGO (easter egg)
- **Logo periódico animado**: Sistema AppLogo con 4 tipos de animación y fade dual
- **Control dinámico**: V-Sync, zoom, fullscreen, escalado, sprites, escenarios
- **Parámetros CLI**: Resolución, zoom, fullscreen, modo inicial configurables
- **Hot-swap de sprites**: Cambio de textura dinámico sin reiniciar física
- **Transiciones LERP**: Cambios de tema suaves (0.5s) sin pérdida de estado

---

## 🎮 Modos de Funcionamiento

### Modos de Aplicación (AppMode)

ViBe3 Physics tiene 4 modos mutuamente excluyentes que controlan el comportamiento general:

| Modo | Tecla | Descripción | Comportamiento |
|------|-------|-------------|----------------|
| **SANDBOX** | - | Modo sandbox (por defecto) | Control manual completo del usuario |
| **DEMO** | `D` | Auto-play completo | Aleatoriza física, temas, escenarios automáticamente |
| **DEMO_LITE** | `Shift+D` | Auto-play solo física | Solo aleatoriza física (gravedad, shapes, impulso) |
| **LOGO** | `K` | Easter egg animado | Muestra logo 3D con PNG_SHAPE (mín. 500 pelotas) |

**Notas:**
- Al entrar a DEMO/DEMO_LITE se aleatoriza el estado inicial
- LOGO configura automáticamente: tema especial, 5000 pelotas, sprite pequeño, PNG_SHAPE
- Presionar misma tecla vuelve a SANDBOX
- DEMO puede saltar automáticamente a LOGO (easter egg)

### Modos de Simulación (SimulationMode)

Controlan el comportamiento físico de las pelotas:

| Modo | Activación | Descripción |
|------|------------|-------------|
| **PHYSICS** | Cursores, `G`, `1-8` | Física normal con gravedad |
| **SHAPE** | `Q-O`, `F` | Figura 3D activa (atracción tipo resorte) |
| **BOIDS** | `C` | Comportamiento de enjambre emergente |

**Cambio automático:**
- Pulsar cursores o `G` → Sale de SHAPE/BOIDS a PHYSICS
- Pulsar `Q-O` → Activa SHAPE y figura específica
- Pulsar `C` → Toggle entre BOIDS ↔ último modo (PHYSICS o SHAPE)
- Pulsar `F` → Toggle entre PHYSICS ↔ última SHAPE usada

---

## 🎹 Controles

### Sistema

| Tecla | Acción |
|-------|--------|
| `H` | **Toggle debug display** (FPS, V-Sync, física, gravedad, modo) |
| `V` | **Toggle V-Sync** ON/OFF |
| `ESC` | **Salir** del programa |

### Ventana y Zoom

| Tecla | Acción |
|-------|--------|
| `F1` | **Zoom Out** (reducir zoom ventana) |
| `F2` | **Zoom In** (aumentar zoom ventana) |
| `F3` | **Toggle Fullscreen** (letterbox, mantiene aspecto) |
| `F4` | **Toggle Real Fullscreen** (resolución nativa) |
| `F5` | **Toggle escalado** INTEGER/LETTERBOX/STRETCH (solo F3) |

### Modos de Aplicación

| Tecla | Acción |
|-------|--------|
| `D` | **Toggle DEMO Mode** (auto-play completo) |
| `Shift+D` | **Toggle DEMO LITE Mode** (auto-play solo física) |
| `K` | **Toggle LOGO Mode** (easter egg con logo 3D) |

### Temas de Colores

| Tecla | Acción |
|-------|--------|
| `B` | **Ciclar temas** (adelante) |
| `Shift+B` | **Ciclar temas** (atrás) |
| `Numpad Enter` | **Cambiar página** de temas (Página 1 ↔ Página 2) |
| `Numpad 1-9, 0` | **Acceso directo** al tema de la página activa |
| `P` | **Pausar/Reanudar** animación de temas dinámicos |

### Sprites y Escenarios

| Tecla | Acción |
|-------|--------|
| `N` | **Cambiar sprite** (tiny → small → normal → big) |
| `1` | **10 pelotas** |
| `2` | **50 pelotas** |
| `3` | **100 pelotas** |
| `4` | **500 pelotas** |
| `5` | **1,000 pelotas** |
| `6` | **5,000 pelotas** |
| `7` | **10,000 pelotas** |
| `8` | **50,000 pelotas** |

### Física y Gravedad

| Tecla | Acción |
|-------|--------|
| `ESPACIO` | **Impulsar** todas las pelotas hacia arriba |
| `G` | **Toggle gravedad** ON/OFF (sale de figuras SIN gravedad) |
| `↑` | **Gravedad hacia ARRIBA** (sale de figuras CON gravedad) |
| `↓` | **Gravedad hacia ABAJO** (sale de figuras CON gravedad) |
| `←` | **Gravedad hacia IZQUIERDA** (sale de figuras CON gravedad) |
| `→` | **Gravedad hacia DERECHA** (sale de figuras CON gravedad) |

### Figuras 3D

| Tecla | Acción |
|-------|--------|
| `F` | **Toggle** modo PHYSICS ↔ última FIGURA activa |
| `Q` | **SPHERE** (Esfera Fibonacci rotante) |
| `W` | **LISSAJOUS** (Curva paramétrica 3D ondeante) |
| `E` | **HELIX** (Espiral helicoidal) |
| `R` | **TORUS** (Toroide/donut rotante) |
| `T` | **CUBE** (Cubo rotante triple XYZ) |
| `Y` | **CYLINDER** (Cilindro rotante) |
| `U` | **ICOSAHEDRON** (Icosaedro D20) |
| `I` | **ATOM** (Núcleo + órbitas electrónicas) |
| `O` | **PNG_SHAPE** (Logo 3D desde PNG) |
| `Numpad +` | **Aumentar escala** de figura (+10%) |
| `Numpad -` | **Reducir escala** de figura (-10%) |
| `Numpad *` | **Reset escala** a 100% |
| `Numpad /` | **Toggle zoom profundidad** (perspectiva 3D ON/OFF) |

### Modo BOIDS

| Tecla | Acción |
|-------|--------|
| `C` | **Toggle BOIDS Mode** (comportamiento de enjambre) |

---

## 🎨 Sistema de Temas (15 Temas - 2 Páginas)

ViBe3 Physics incluye **15 temas visuales** organizados en **2 páginas** (9 estáticos + 1 dinámico en Página 1, 5 dinámicos en Página 2). Los temas dinámicos tienen animación de colores en tiempo real.

![ViBe3 Physics - Gameplay](https://php.sustancia.synology.me/images/vibe3_physics/captura_vibe3_physics_2.png)

### Controles de Temas

- **`B`**: Ciclar entre TODOS los temas (adelante)
- **`Shift+B`**: Ciclar entre TODOS los temas (atrás)
- **`Numpad Enter`**: Cambiar entre Página 1 y Página 2
- **`Numpad 1-9, 0`**: Acceso directo al tema según página activa
- **`P`**: Pausar/reanudar animación de temas dinámicos

### Página 1 (Temas Estáticos + 1 Dinámico)

| Tecla | Tema | Tipo | Descripción |
|-------|------|------|-------------|
| `Numpad 1` | **ATARDECER** | Estático | Naranjas, rojos, amarillos, rosas |
| `Numpad 2` | **OCÉANO** | Estático | Azules, turquesas, blancos |
| `Numpad 3` | **NEÓN** | Estático | Cian, magenta, verde lima, amarillo vibrante |
| `Numpad 4` | **BOSQUE** | Estático | Verdes, marrones, amarillos otoño |
| `Numpad 5` | **RGB** | Estático | Círculo cromático 24 colores (fondo blanco) |
| `Numpad 6` | **MONOCROMO** | Estático | Fondo negro degradado, sprites blancos |
| `Numpad 7` | **LAVANDA** | Estático | Degradado violeta-azul, pelotas amarillo dorado |
| `Numpad 8` | **CARMESÍ** | Estático | Fondo negro-rojo, pelotas rojas uniformes |
| `Numpad 9` | **ESMERALDA** | Estático | Fondo negro-verde, pelotas verdes uniformes |
| `Numpad 0` | **AMANECER** | **Dinámico** | Noche → Alba → Día (loop 12s) |

### Página 2 (Temas Dinámicos Animados)

| Tecla | Tema | Tipo | Descripción |
|-------|------|------|-------------|
| `Numpad 1` | **OLAS OCEÁNICAS** | **Dinámico** | Azul oscuro ↔ Turquesa (loop 8s) |
| `Numpad 2` | **PULSO NEÓN** | **Dinámico** | Negro ↔ Neón brillante (ping-pong 3s) |
| `Numpad 3` | **FUEGO** | **Dinámico** | Brasas → Llamas → Inferno (loop 10s) |
| `Numpad 4` | **AURORA** | **Dinámico** | Verde → Violeta → Cian (loop 14s) |
| `Numpad 5` | **VOLCÁN** | **Dinámico** | Ceniza → Erupción → Lava (loop 12s) |
| `Numpad 6-9, 0` | *(sin asignar)* | - | Sin función en Página 2 |

### Características Técnicas

- **Transiciones LERP**: Interpolación suave (0.5s) entre temas
- **Fondos degradados**: 2 colores interpolados verticalmente
- **Paletas por tema**: 8-24 colores (RGB tiene 24, resto 8)
- **Sin pérdida de estado**: Mantiene física, posiciones, velocidades
- **Compatible**: Con todos los modos y escenarios

---

## 🔷 Sistema de Figuras 3D (9 Figuras)

Sistema polimórfico que convierte pelotas en formas geométricas 3D proyectadas en 2D.

### Figuras Disponibles

#### 🌐 SPHERE (Tecla `Q`)
- **Algoritmo**: Fibonacci Sphere (distribución uniforme de puntos)
- **Rotación**: Dual (ejes X e Y)
- **Efecto**: Esfera rotante clásica estilo demoscene

#### 🌊 LISSAJOUS (Tecla `W`)
- **Algoritmo**: Curva paramétrica 3D (frecuencias 3:2:1)
- **Animación**: Fase oscilante + rotación global
- **Efecto**: Malla ondeante compleja

#### 🧬 HELIX (Tecla `E`)
- **Algoritmo**: Espiral helicoidal paramétrica (3 vueltas)
- **Animación**: Rotación en eje Y + fase vertical
- **Efecto**: DNA/hélice rotante

#### 🍩 TORUS (Tecla `R`)
- **Algoritmo**: Toroide paramétrico (radio mayor + menor)
- **Rotación**: Triple eje (X, Y, Z) con velocidades diferentes
- **Efecto**: Donut flotante estilo demoscene

#### 🎲 CUBE (Tecla `T`)
- **Distribución inteligente**:
  - 1-8 pelotas: Solo vértices (8 puntos)
  - 9-26 pelotas: Vértices + caras + aristas (26 puntos)
  - 27+ pelotas: Grid volumétrico 3D uniforme
- **Rotación**: Triple (X, Y, Z simultáneos)
- **Efecto**: Cubo Rubik rotante

#### 🏛️ CYLINDER (Tecla `Y`)
- **Algoritmo**: Cilindro con tapas circulares
- **Rotación**: Eje Y (spin horizontal)
- **Efecto**: Columna griega rotante

#### ⚛️ ICOSAHEDRON (Tecla `U`)
- **Algoritmo**: Poliedro regular de 20 caras (12 vértices)
- **Geometría**: Proporción áurea
- **Rotación**: Triple eje caótico
- **Efecto**: Dado D20 flotante

#### ⚛️ ATOM (Tecla `I`)
- **Estructura**: Núcleo central + 3 órbitas elípticas
- **Animación**: Electrones en movimiento orbital
- **Rotación**: Órbitas perpendiculares entre sí
- **Efecto**: Átomo de Bohr animado

#### 🖼️ PNG_SHAPE (Tecla `O`)
- **Algoritmo**: Carga imagen PNG 1-bit y extrude a volumen 3D
- **Animación**: Rotación "legible" (flip ocasional cada 2-4s)
- **Profundidad**: 15 capas de extrusión
- **Efecto**: Logo 3D con volteretas
- **Uso**: Modo LOGO carga `data/logo/logo.png` automáticamente

### Características Físicas

- **Sistema spring-damper**: Transición suave con Ley de Hooke
- **Profundidad Z simulada**: Color modulado (oscuro=fondo, brillante=frente)
- **Z-sorting**: Painter's Algorithm para oclusión correcta
- **Zoom por profundidad**: Perspectiva 3D (50%-150% según Z)
- **Escala dinámica**: Control manual Numpad +/- (30%-300%)
- **Protección clipping**: Límites automáticos según resolución

### Parámetros Configurables (defines.h)

```cpp
// Física compartida (spring-damper)
SHAPE_SPRING_K = 800.0f;          // Rigidez resorte (N/m)
SHAPE_DAMPING_BASE = 60.0f;       // Amortiguación base
SHAPE_DAMPING_NEAR = 150.0f;      // Absorción cerca del punto

// Control manual de escala
SHAPE_SCALE_MIN = 0.3f;           // Mínimo 30%
SHAPE_SCALE_MAX = 3.0f;           // Máximo 300%
SHAPE_SCALE_STEP = 0.1f;          // Incremento 10%
```

---

## 🐦 Modo BOIDS (Comportamiento de Enjambre)

Sistema de inteligencia de enjambre basado en **3 reglas de Reynolds**:

### Reglas de Comportamiento

1. **Separación**: Evitar colisiones con vecinos cercanos
2. **Alineación**: Seguir dirección promedio del grupo
3. **Cohesión**: Moverse hacia el centro del grupo local

### Características

- **Toggle**: Tecla `C` (alterna BOIDS ↔ último modo)
- **Bordes como obstáculos**: Evitan bordes de pantalla
- **Time-based**: Física independiente del framerate
- **Compatible**: Con temas, escenarios (1-100,000 boids)
- **Gravedad OFF**: Desactiva gravedad automáticamente

### Parámetros Ajustables (defines.h)

```cpp
// Velocidades
BOIDS_MAX_SPEED = 200.0f;         // Velocidad máxima (px/s)
BOIDS_MAX_FORCE = 400.0f;         // Fuerza máxima (px/s²)

// Pesos de comportamiento
BOIDS_SEPARATION_WEIGHT = 1.5f;   // Peso separación
BOIDS_ALIGNMENT_WEIGHT = 1.0f;    // Peso alineación
BOIDS_COHESION_WEIGHT = 1.0f;     // Peso cohesión

// Radios de detección
BOIDS_SEPARATION_RADIUS = 25.0f;  // Radio separación (px)
BOIDS_NEIGHBOR_RADIUS = 50.0f;    // Radio vecindad (px)
```

---

## 🖼️ Sistema AppLogo (Logo Periódico)

Logo animado que aparece periódicamente en modos **DEMO**, **DEMO_LITE** y **LOGO**. No aparece en modo SANDBOX.

### Características

- **Intervalo**: Cada 5 segundos (configurable)
- **Duración visible**: 10 segundos (configurable)
- **Animación entrada/salida**: 2 segundos con fade lineal
- **4 tipos de animación aleatoria**:
  - **ZOOM_ONLY**: Zoom simple de 120% → 100%
  - **ELASTIC_STICK**: Efecto elástico tipo pegatina
  - **ROTATE_SPIRAL**: Rotación en espiral de 0% → 100%
  - **BOUNCE_SQUASH**: Rebote con squash & stretch
- **Sistema dual logo**: Dos logos superpuestos con animación sincronizada
- **Retraso Logo 2**: 0.25s detrás de Logo 1 (efecto echo)
- **Posición**: Esquina inferior derecha con padding 10%
- **Tamaño**: 40% de altura de pantalla
- **Pre-escalado**: 2 versiones (base + resolución nativa) para calidad óptima

### Configuración (defines.h)

```cpp
APPLOGO_DISPLAY_INTERVAL = 5.0f;     // Intervalo entre apariciones (s)
APPLOGO_DISPLAY_DURATION = 10.0f;    // Duración visible (s)
APPLOGO_ANIMATION_DURATION = 2.0f;   // Duración fade entrada/salida (s)
APPLOGO_HEIGHT_PERCENT = 0.4f;       // Altura = 40% pantalla
APPLOGO_PADDING_PERCENT = 0.1f;      // Padding = 10% desde bordes
APPLOGO_LOGO2_DELAY = 0.25f;         // Retraso Logo 2 (s)
```

---

## ⚙️ Parámetros de Línea de Comandos

ViBe3 Physics acepta parámetros CLI para configurar resolución, zoom, fullscreen y modo inicial.

### Sintaxis

```bash
vibe3_physics [opciones]
```

### Opciones Disponibles

| Parámetro | Descripción | Default | Ejemplo |
|-----------|-------------|---------|---------|
| `-w, --width <px>` | Ancho de resolución | 320 | `-w 1920` |
| `-h, --height <px>` | Alto de resolución | 240 | `-h 1080` |
| `-z, --zoom <n>` | Zoom de ventana | 3 (auto si -w/-h) | `-z 2` |
| `-f, --fullscreen` | Fullscreen letterbox (F3) | OFF | `-f` |
| `-F, --real-fullscreen` | Fullscreen nativo (F4) | OFF | `-F` |
| `-m, --mode <mode>` | Modo inicial | sandbox | `-m demo` |
| `--help` | Mostrar ayuda | - | `--help` |

### Modos Disponibles

- **`sandbox`**: Modo manual (default)
- **`demo`**: Auto-play completo (aleatoriza todo al iniciar)
- **`demo-lite`**: Auto-play solo física (aleatoriza física al iniciar)
- **`logo`**: Easter egg (configura tema, PNG_SHAPE, 5000 pelotas)

### Ejemplos de Uso

```bash
# Resolución default (320x240 zoom 3)
./vibe3_physics

# 1080p en ventana 1x
./vibe3_physics -w 1920 -h 1080

# 640x480 zoom 2 (ventana 1280x960)
./vibe3_physics -w 640 -h 480 -z 2

# Fullscreen letterbox (mantiene aspecto)
./vibe3_physics -f

# Fullscreen nativo (resolución de monitor)
./vibe3_physics -F

# Iniciar directamente en modo DEMO
./vibe3_physics -m demo

# Fullscreen + modo LOGO
./vibe3_physics -F --mode logo
```

### Validaciones

- **Ancho mínimo**: 320px
- **Alto mínimo**: 240px
- **Zoom automático**: Si resolución > pantalla, usa default
- **Zoom máximo**: Ajustado según pantalla disponible

---

## 📊 Información en Pantalla

### Display Normal

- **Esquina superior derecha**: Contador FPS en tiempo real (**amarillo**)

### Debug Display (Tecla `H`)

Cuando se activa con `H`, muestra información técnica detallada:

- **Línea 1 (sup. izq.)**: Estado V-Sync (**VSYNC ON/OFF** en **cian**)
- **Línea 2 (sup. der.)**: Contador FPS (**amarillo**)
- **Líneas 3-5**: Valores física primera pelota (**magenta**):
  - `GRAV` - Magnitud gravedad (px/s²)
  - `VY` - Velocidad vertical (px/s)
  - `SURFACE` - En superficie (YES/NO)
  - `LOSS` - Coeficiente rebote (0.30-0.95)
- **Línea 6**: Dirección gravedad (**GRAVITY UP/DOWN/LEFT/RIGHT** en **amarillo**)
- **Línea 7**: Tema activo (**THEME SUNSET/OCEAN/...** en **amarillo claro**)
- **Línea 8**: Modo simulación (**MODE PHYSICS/SHAPE/BOIDS** en **verde claro**)

### Notificaciones Temporales

Sistema de notificaciones superior centrado con animación slide + fade:
- **Cambio de tema**: "TEMA: ATARDECER" (2s)
- **Cambio de sprite**: "SPRITE: SMALL" (2s)
- **Cambio de escenario**: "ESCENARIO: 5000 PELOTAS" (2s)
- **Cambio de modo**: "MODO DEMO" / "MODO SANDBOX" (2s)

---

## 🏗️ Estructura del Proyecto

```
vibe3_physics/
├── source/
│   ├── main.cpp                    # Entry point y parseo CLI
│   ├── engine.h/cpp                # Motor principal con loop y rendering
│   ├── ball.h/cpp                  # Clase Ball - física de pelotas
│   ├── defines.h                   # Constantes y configuración global
│   ├── app_logo.h/cpp              # Sistema de logo periódico
│   ├── logo_scaler.h/cpp           # Pre-escalado de logos (stb_image_resize2)
│   ├── theme_manager.h/cpp         # Gestión de temas y transiciones LERP
│   ├── spatial_grid.h/cpp          # Grid espacial para optimización BOIDS
│   │
│   ├── boids_mgr/
│   │   └── boid_manager.h/cpp      # Gestor de comportamiento BOIDS
│   │
│   ├── input/
│   │   └── input_handler.h/cpp     # Manejo de teclado y eventos SDL
│   │
│   ├── scene/
│   │   └── scene_manager.h/cpp     # Gestión de pelotas y escenarios
│   │
│   ├── shapes/                     # Sistema polimórfico de figuras 3D
│   │   ├── shape.h                     # Interfaz abstracta Shape
│   │   ├── sphere_shape.h/cpp          # Fibonacci Sphere
│   │   ├── cube_shape.h/cpp            # Cubo rotante triple
│   │   ├── helix_shape.h/cpp           # Espiral helicoidal
│   │   ├── torus_shape.h/cpp           # Toroide/donut
│   │   ├── lissajous_shape.h/cpp       # Curva paramétrica 3D
│   │   ├── cylinder_shape.h/cpp        # Cilindro rotante
│   │   ├── icosahedron_shape.h/cpp     # Icosaedro D20
│   │   ├── atom_shape.h/cpp            # Átomo con órbitas
│   │   └── png_shape.h/cpp             # Logo 3D desde PNG
│   │
│   ├── shapes_mgr/
│   │   └── shape_manager.h/cpp     # Gestor de figuras 3D
│   │
│   ├── state/
│   │   └── state_manager.h/cpp     # Gestor de modos (DEMO/LOGO/SANDBOX)
│   │
│   ├── themes/
│   │   ├── static_theme.h/cpp      # Temas estáticos
│   │   └── dynamic_theme.h/cpp     # Temas dinámicos animados
│   │
│   ├── ui/
│   │   ├── ui_manager.h/cpp        # Gestor de UI (HUD, FPS, debug)
│   │   ├── notifier.h/cpp          # Sistema de notificaciones temporales
│   │   └── help_overlay.h/cpp      # Overlay de ayuda (no implementado)
│   │
│   └── external/                   # Utilidades externas
│       ├── sprite.h/cpp                # Renderizado de sprites
│       ├── texture.h/cpp               # Gestión de texturas (con pack)
│       ├── dbgtxt.h                    # Sistema de debug text
│       ├── mouse.h                     # Utilidades de mouse
│       ├── stb_image.h                 # Carga de imágenes (stb)
│       └── stb_image_resize2.h         # Resize de imágenes (stb)
│
├── data/                           # Recursos del juego
│   ├── balls/                          # Texturas de pelotas
│   │   ├── tiny.png                        # 4x4 píxeles
│   │   ├── small.png                       # 6x6 píxeles
│   │   ├── normal.png                      # 10x10 píxeles
│   │   └── big.png                         # 16x16 píxeles
│   ├── logo/                           # Logos para AppLogo
│   │   ├── logo.png                        # Logo principal (PNG 1-bit)
│   │   └── logo2.png                       # Logo secundario
│   └── fonts/
│       └── determination.ttf           # Fuente para texto
│
├── CMakeLists.txt                  # Configuración CMake
├── Makefile                        # Configuración Make
├── CLAUDE.md                       # Seguimiento de desarrollo
├── README.md                       # Este archivo
└── .gitignore                      # Archivos ignorados por Git
```

---

## 🔧 Requisitos del Sistema

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

### Instalación de SDL3

#### Windows (MinGW)
```bash
# Usando vcpkg
vcpkg install sdl3

# O compilar desde fuente
git clone https://github.com/libsdl-org/SDL
cd SDL
mkdir build && cd build
cmake ..
make
sudo make install
```

#### Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install libsdl3-dev

# Si no está disponible, compilar desde fuente
```

#### Linux (Arch)
```bash
sudo pacman -S sdl3
```

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

---

## 🚀 Compilación

### Opción 1: CMake (Recomendado)

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

### Opción 2: Make directo

```bash
make
```

---

## ▶️ Ejecución

### Ejecución Basic

```bash
# Linux/macOS
./vibe3_physics

# Windows
./vibe3_physics.exe
```

### Ejemplos con Parámetros

```bash
# 1080p fullscreen + modo DEMO
./vibe3_physics -w 1920 -h 1080 -F -m demo

# 720p zoom 2 + modo LOGO
./vibe3_physics -w 1280 -h 720 -z 2 -m logo

# Default con fullscreen letterbox
./vibe3_physics -f
```

---

## 📊 Detalles Técnicos

### Configuración Default

- **Resolución**: 320x240 píxeles (escalado x3 = 960x720 ventana)
- **Sistema de timing**: Delta time independiente del framerate
- **Física**: Gravedad 720 px/s², rebotes con pérdida 0.30-0.95
- **Tamaño de pelota**: Dinámico (4, 6, 10, 16 según sprite)
- **V-Sync**: Activado por defecto, controlable dinámicamente
- **Temas**: 15 temas (9 estáticos + 6 dinámicos)
- **Figuras 3D**: 9 figuras completas con física spring-damper

### Arquitectura del Código

El engine sigue una arquitectura **component-based** con separación de responsabilidades:

1. **Engine**: Bucle principal (delta time, update, events, render)
2. **SceneManager**: Gestión de pelotas y escenarios
3. **ShapeManager**: Gestión de figuras 3D
4. **BoidManager**: Comportamiento de enjambre
5. **StateManager**: Control de modos (DEMO/LOGO/SANDBOX)
6. **ThemeManager**: Temas y transiciones LERP
7. **UIManager**: HUD, FPS, debug, notificaciones
8. **InputHandler**: Procesamiento de teclado
9. **AppLogo**: Sistema de logo periódico

### Sistema de Delta Time

**Conversión de unidades (frame-based → time-based):**

| Parámetro | Frame-Based | Time-Based | Conversión |
|-----------|-------------|------------|------------|
| Velocidad | px/frame | px/segundo | ×60 |
| Gravedad | px/frame² | px/segundo² | ×3600 (60²) |
| Física | Cada 16.67ms | Cada delta_time | Proporcional |

**Beneficios:**
- ✅ Velocidad consistente entre 60Hz, 75Hz, 144Hz+
- ✅ V-Sync independiente (misma velocidad ON/OFF)
- ✅ Física precisa y predecible
- ✅ Escalable a cualquier framerate

### Batch Rendering

**Rendimiento conseguido:**
- **50,000 pelotas**: >75 FPS (mejora de 750% vs rendering individual)
- **100,000 pelotas**: Fluido y jugable
- **Una sola llamada** `SDL_RenderGeometry` por frame
- **Overhead mínimo**: Acumulación de vértices e índices en vectores

---

## 🛠️ 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

- **Smart pointers**: `unique_ptr`, `shared_ptr` para gestión de memoria
- **RAII**: Para recursos SDL (window, renderer, texturas)
- **Separación de responsabilidades**: Arquitectura component-based
- **Configuración multiplataforma**: Windows, Linux, macOS
- **Filtro nearest neighbor**: Texturas pixel-perfect
- **Sistema de métricas**: FPS, V-Sync, física en tiempo real
- **Resource pack**: Sistema de empaquetado de recursos (opcional)

---

## 🐛 Problemas Conocidos

Ninguno conocido. El sistema está completamente funcional con delta time, batch rendering, temas, figuras 3D, BOIDS y modos de aplicación implementados.

---

## 📸 Capturas de Pantalla

*(Pendiente de añadir capturas de pantalla)*

---

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

*ViBe3 Physics - JailDesigner 2025*