vibe3-physics/ROADMAP.md

# ROADMAP - ViBe3 Physics

## Estado Actual ✅

### Figuras 3D (8/8 Completadas)
- ✅ Q - SPHERE (Esfera Fibonacci)
- ✅ W - WAVE_GRID (Malla ondeante) - ⚠️ Necesita mejora de movimiento
- ✅ E - HELIX (Espiral helicoidal)
- ✅ R - TORUS (Toroide/donut)
- ✅ T - CUBE (Cubo rotante)
- ✅ Y - CYLINDER (Cilindro) - ⚠️ Necesita rotación multi-eje
- ✅ U - ICOSAHEDRON (Icosaedro D20)
- ✅ I - ATOM (Núcleo + órbitas)

### Temas Visuales (6/6 Completadas)
- ✅ SUNSET (Atardecer)
- ✅ OCEAN (Océano)
- ✅ NEON (Neón vibrante)
- ✅ FOREST (Bosque)
- ✅ RGB (Círculo cromático matemático)
- ✅ MONOCHROME (Monocromo - blanco puro)

### Sistemas de Presentación
- ✅ Transiciones LERP entre temas (0.5s suaves)
- ✅ Carga dinámica de texturas desde data/balls/
- ✅ Hot-swap de sprites con tecla N (cicla entre todas las texturas)
- ✅ PNG_SHAPE (O) - Logo "JAILGAMES" con rotación legible

---

## Mejoras de Presentación 🎨

### 1. ⏳ Mejorar Animaciones de Figuras 3D
**Descripción:** Añadir movimientos más dinámicos e interesantes a algunas figuras
**Prioridad:** Media
**Estimación:** 1.5 horas
**Detalles:**

#### CYLINDER (Y):
- **Rotación actual:** Solo eje Y (spin horizontal continuo)
- **Mejora propuesta:** Rotaciones multi-eje con cambios periódicos
  - Rotación principal en eje Y (como ahora)
  - Cada 3-5 segundos: tumbling en eje X o Z durante 1-2 segundos
  - Efecto visual: "dar una vuelta" sobre otro eje ocasionalmente
  - Transiciones suaves con aceleración/desaceleración

#### WAVE_GRID (W):
- **Rotación actual:** XY girando como esfera (confuso)
- **Mejora propuesta:** Vista frontal con pivoteo sutil
  - **Vista principal:** Paralela a pantalla (mirando de frente)
  - **Movimiento:** Pivoteo en centro con esquinas hacia adelante/atrás
  - Ejemplo: esquina superior-derecha se aleja (Z-), inferior-izquierda se acerca (Z+)
  - Movimiento ondulatorio sincronizado: olas + pivoteo crea efecto "océano"
  - **Opcional:** Rotación completa ocasional (cada 10-15s) como transición

**Implementación técnica:**
- Añadir `rotation_mode_` y `mode_timer_` a cada shape
- Estados: NORMAL, TRANSITION, ALTERNATIVE
- Interpolación suave entre modos de rotación

### 2. ✅ Modo DEMO (Auto-play)
**Descripción:** Modo demostración automática con acciones aleatorias
**Prioridad:** Alta
**Estado:** ✅ COMPLETADO
**Detalles:**
- ✅ Toggle con tecla `D`
- ✅ Timer que ejecuta acciones cada 3-8 segundos (configurable)
- ✅ Acciones: gravedad, figuras, temas, escenarios, impulso, profundidad, escala, sprite
- ✅ Secuencia pseudo-aleatoria con pesos configurables (defines.h)
- ✅ Totalmente interactivo - usuario puede seguir usando controles
- ✅ Indicador visual "DEMO MODE" centrado en pantalla (naranja)
- ✅ Eliminado sistema auto-restart antiguo (ya no necesario)

### 3. ⏳ Resolución Lógica Configurable
**Descripción:** Especificar resolución lógica por parámetros de línea de comandos
**Prioridad:** Media
**Estimación:** 1 hora
**Detalles:**
- Parámetros `--width <px> --height <px>` o `-w <px> -h <px>`
- Parámetro `--fullscreen` o `-f` (opcional)
- Defaults: 1280x720 en ventana
- Ejemplo: `./vibe3_physics -w 1920 -h 1080 -f`
- Validación de valores (mínimo 640x480, máximo según SDL_DisplayMode)
- Help text con `-h` o `--help`

### 4. 🐛 Corregir Escalado de Pelotas en Reposo
**Descripción:** Las pelotas cambian de tamaño cuando están quietas (bug visual)
**Prioridad:** Alta (bug visible)
**Estimación:** 30 minutos
**Detalles:**
- **Síntoma:** Pelotas en reposo (velocidad ≈ 0) se escalan incorrectamente
- **Posible causa:**
  - Scale factor calculado desde velocidad o energía
  - División por cero o valor muy pequeño
  - Interpolación incorrecta en modo transición
- **Investigar:** Ball::render(), scale calculations, depth brightness
- **Solución esperada:** Tamaño constante independiente de velocidad

### 5. ⏳ Sistema de Release
**Descripción:** Empaquetado para distribución standalone
**Prioridad:** Baja
**Estimación:** 30 minutos
**Detalles:**
- Crear carpeta `release/`
- Script Python `pack_resources.py` para empaquetar
- Incluir SDL3.dll
- Incluir icon.png (si existe)
- Empaquetar `data/` en archivo .dat o .zip
- Target `make release` en Makefile
- README.txt con instrucciones

---

## Futuras Mejoras (Ideas)

### Performance
- [ ] Spatial partitioning para colisiones ball-to-ball
- [ ] Level-of-detail para 100K+ pelotas
- [ ] GPU compute shaders para física masiva

### Efectos Visuales
- [ ] Trails (estelas de movimiento)
- [ ] Heatmaps de velocidad/energía
- [ ] Bloom/glow para sprites

### Física Avanzada
- [ ] Colisiones entre partículas
- [ ] Viento (fuerza horizontal)
- [ ] Campos magnéticos (atracción/repulsión)
- [ ] Turbulencia

### Shapes PNG
- [ ] **Voxelización 3D para PNG_SHAPE** (Enfoque B)
  - Actualmente: Extrusión 2D simple (píxeles → capas Z)
  - Futuro: Voxelización real con detección de interior/exterior
  - Permite formas 3D más complejas desde imágenes
  - Rotación volumétrica en vez de extrusión plana

### Interactividad
- [ ] Mouse: click para aplicar fuerzas
- [ ] Mouse: drag para crear campos
- [ ] Mouse wheel: ajustar intensidad

---

## Historial de Cambios

### 2025-10-04 (Sesión 5) - PNG Shape + Texturas Dinámicas
- ✅ **PNG_SHAPE implementado** - Tecla O para activar logo "JAILGAMES"
- ✅ Carga de PNG 1-bit con stb_image
- ✅ Extrusión 2D (Enfoque A) - píxeles → capas Z
- ✅ Detección de bordes vs relleno completo (configurable)
- ✅ Tamaño 80% pantalla (como otras figuras)
- ✅ Rotación "legible" - De frente con volteretas ocasionales (3-8s idle)
- ✅ Excluido de DEMO/DEMO_LITE (logo especial)
- ✅ **Sistema de texturas dinámicas** - Carga automática desde data/balls/
- ✅ Tecla N cicla entre todas las texturas PNG encontradas
- ✅ Orden alfabético con normal.png primero por defecto
- ✅ Display dinámico del nombre de textura (uppercase)
- 📝 Preparado para voxelización 3D (Enfoque B) en futuro

### 2025-10-04 (Sesión 4) - Modo DEMO
- ✅ **Implementado Modo DEMO (auto-play)** - Tecla D para toggle
- ✅ Sistema de acciones aleatorias cada 3-8 segundos (configurable)
- ✅ 8 tipos de acciones con pesos de probabilidad ajustables
- ✅ Totalmente interactivo - usuario puede seguir controlando
- ✅ Display visual "DEMO MODE" centrado en naranja
- ✅ Mejoras animaciones 3D: tumbling en cilindro + pivoteo en wave grid
- ❌ Eliminado sistema auto-restart antiguo (ya no necesario)

### 2025-10-04 (Sesión 3)
- ✅ Implementado tema MONOCHROME (6º tema)
- ✅ Sistema LERP para transiciones suaves de temas (0.5s)
- ✅ Hot-swap de sprites con tecla N (ball.png ↔ ball_small.png)
- ✅ Tamaño dinámico de pelotas desde texture->getWidth()
- ✅ Ajuste de posiciones inteligente al cambiar sprite
- 📝 Añadidas mejoras propuestas para CYLINDER y WAVE_GRID

### 2025-10-03 (Sesión 2)
- ✅ Implementadas 8 figuras 3D (SPHERE, WAVE_GRID, HELIX, TORUS, CUBE, CYLINDER, ICOSAHEDRON, ATOM)
- ✅ Sistema polimórfico de shapes con herencia virtual

### 2025-10-02 (Sesión 1)
- ✅ Migración desde vibe1_delta
- ✅ Sistema de gravedad direccional (4 direcciones)
- ✅ Coeficientes de rebote variables (0.30-0.95)
- ✅ 5 temas de colores iniciales

---

**Última actualización:** 2025-10-04