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
**Estado:** ✅ COMPLETADO
**Detalles:**

#### CYLINDER (Y):
- ✅ **Rotación principal en eje Y** (spin horizontal continuo)
- ✅ **Tumbling ocasional en eje X** cada 3-5 segundos
- ✅ Transiciones suaves con ease-in-out (1.5s duración)
- ✅ Efecto visual: cilindro "se da una vuelta" ocasionalmente

#### WAVE_GRID (W):
- ✅ **Vista frontal paralela a pantalla** (sin rotación confusa)
- ✅ **Pivoteo sutil en ejes X e Y**
- ✅ Esquinas se mueven adelante/atrás según posición
- ✅ Movimiento ondulatorio + pivoteo = efecto "océano"
- ✅ Velocidades lentas (0.3-0.5 rad/s) para organicidad

### 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
**Estado:** ✅ COMPLETADO
**Detalles:**
- ✅ Parámetros `-w/--width <px>` y `-h/--height <px>`
- ✅ Parámetro `-f/--fullscreen` para pantalla completa
- ✅ Defaults: 1280x720 en ventana (si no se especifica)
- ✅ Validación: mínimo 640x480
- ✅ Help text con `--help`
- Ejemplo: `./vibe3_physics -w 1920 -h 1080 -f`

### 4. ✅ Implementar Modo Logo (Easter Egg)
**Descripción:** Modo especial que muestra el logo JAILGAMES como "marca de agua"
**Prioridad:** Alta (característica distintiva)
**Estado:** ✅ COMPLETADO
**Detalles:**

#### ✅ Configuración Modo Logo:
- ✅ **Figura:** Solo PNG_SHAPE (logo JAILGAMES)
- ✅ **Textura:** Siempre "tiny" (pelota más pequeña)
- ✅ **Tema:** Siempre MONOCHROME (blanco puro)
- ✅ **Escala:** 120% (figuras más grandes que normal)
- ✅ **Pelotas mínimas:** 500
- ✅ **Tecla manual:** K (activa/desactiva modo logo)

#### ✅ Comportamiento en Modo Logo:
- ✅ Alterna entre modo SHAPE y modo PHYSICS (como DEMO)
- ✅ Mantiene configuración fija (no cambia tema/textura/escala)
- ✅ Es como un "DEMO específico del logo"

#### ✅ Integración con DEMO LITE:
- ✅ **Requisitos para salto automático:**
  - Mínimo 500 pelotas
  - Tema MONOCHROME activo
  - Si se cumplen → cambia automáticamente textura a "tiny" y escala a 120%
- ✅ **Duración:** Menos tiempo que DEMO normal (es un "recordatorio")
- ✅ **Después:** Vuelve a DEMO LITE normal

#### ✅ Integración con DEMO:
- ✅ **Requisitos:** Mínimo 500 pelotas
- ✅ **Acción:** Cambia automáticamente a: MONOCHROME + tiny + escala 120%
- ✅ **Duración:** Menos tiempo que acciones normales
- ✅ **Después:** Vuelve a DEMO normal

#### ✅ Proporción temporal sugerida:
- ✅ DEMO/DEMO_LITE normal: 80-90% del tiempo
- ✅ Modo Logo: 10-20% del tiempo (aparición ocasional como "easter egg")

### 5. ⏳ Mejorar Sistema de Vértices PNG_SHAPE
**Descripción:** Con 50 pelotas no activa modo vértices correctamente
**Prioridad:** Baja (mejora visual)
**Estimación:** 1 hora
**Detalles:**
- **Comportamiento actual:** Con 50 pelotas usa filas alternas en bordes
- **Comportamiento deseado:** Activar modo VÉRTICES (extremos izq/der de cada fila)
- **Problema:** Condición `num_points < 150` no es suficientemente agresiva
- **Solución propuesta:**
  - Ajustar umbrales de activación de vértices
  - Mejorar algoritmo extractCornerVertices() para detectar puntos clave
  - Considerar densidad de píxeles en decisión (no solo cantidad absoluta)

### 5. 🐛 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

### 6. ⏳ 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 + CLI
- ✅ **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)
- ✅ Fix: Z forzado a máximo cuando está de frente (texto brillante)
- ✅ 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)
- ✅ **Física mejorada SHAPE** - Constantes separadas de ROTOBALL
- ✅ Pegajosidad 2.67x mayor (SPRING_K=800 vs 300)
- ✅ Pelotas se adhieren mejor durante rotaciones rápidas
- ✅ **Parámetros de línea de comandos** - `-w/-h/-f/--help`
- ✅ Resolución configurable (mínimo 640x480)
- 📝 Preparado para voxelización 3D (Enfoque B) en futuro

### 2025-10-04 (Sesión 4) - Modo DEMO + Mejoras Animaciones
- ✅ **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
- ✅ CYLINDER: tumbling ocasional en eje X cada 3-5s con ease-in-out
- ✅ WAVE_GRID: pivoteo sutil paralelo a pantalla (efecto océano)
- ❌ 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