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 (7/7 Completadas)
- ✅ SUNSET (Atardecer)
- ✅ OCEAN (Océano)
- ✅ NEON (Neón vibrante)
- ✅ FOREST (Bosque)
- ✅ RGB (Círculo cromático matemático)
- ✅ MONOCHROME (Monocromo - blanco puro)
- ✅ LAVENDER (Lavanda - degradado violeta-azul, pelotas doradas)

### 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
**Estado:** ✅ COMPLETADO
**Detalles:**
- ✅ Carpeta `release/` con recursos
- ✅ ResourcePack sistema de empaquetado binario (VBE3 format)
- ✅ Tool `pack_resources` para generar resources.pack
- ✅ SDL3.dll incluido en release
- ✅ Carga híbrida: resources.pack con fallback a data/
- ✅ Target `make windows_release` en Makefile
- ✅ ZIP generado: vibe3_physics-YYYY-MM-DD-win32-x64.zip

### 7. ⏳ Logo/Autor Sobreimpreso (Watermark)
**Descripción:** Mostrar logo JAILGAMES en esquina con animación periódica
**Prioridad:** Media
**Estimación:** 2 horas
**Detalles:**
- **Posición:** Esquina inferior derecha (o configurable)
- **Aparición:** Cada X segundos (ej: cada 30-60s)
- **Animación entrada:** Fade-in + slide desde fuera de pantalla
- **Duración visible:** 3-5 segundos
- **Animación salida:** Fade-out + slide hacia fuera
- **Rendering:** Textura PNG con alpha blending
- **Configuración:**
  - Intervalo de aparición (LOGO_WATERMARK_INTERVAL)
  - Duración visible (LOGO_WATERMARK_DURATION)
  - Tamaño relativo a pantalla (ej: 10-15% ancho)
  - Opacidad máxima (ej: 70-80% alpha)
- **Integración:** No interfiere con debug display ni modos DEMO/LOGO
- **Asset:** Reutilizar data/jailgames_logo.png existente

### 8. ⏳ Mejorar Sistema de Renderizado de Texto
**Descripción:** Actualizar tipografía y mejorar clase dbgtxt para mejor legibilidad
**Prioridad:** Media
**Estimación:** 3-4 horas
**Detalles:**
- **Problemas actuales:**
  - Fuente bitmap actual poco legible en resoluciones altas
  - Sistema dbgtxt limitado (solo fuente fija)
  - Sin suavizado (aliasing visible)
  - Tamaño no escala con resolución
- **Soluciones propuestas:**
  - **Opción A - SDL_ttf:** Usar fuentes TrueType (.ttf)
    - Mayor calidad y escalabilidad
    - Antialiasing nativo
    - Soporte Unicode completo
    - Requiere añadir dependencia SDL3_ttf
  - **Opción B - Bitmap mejorada:** Nueva fuente bitmap de mayor calidad
    - Sin dependencias adicionales
    - Textura PNG con caracteres ASCII
    - Escalado nearest-neighbor para estética pixel-art
    - Más control sobre aspecto retro
- **Mejoras clase dbgtxt:**
  - Soporte múltiples tamaños (pequeño/normal/grande)
  - Sombra/outline configurable para mejor contraste
  - Alineación (izquierda/centro/derecha)
  - Color y alpha por texto individual
  - Medición de ancho de texto (para centrado dinámico)
- **Assets necesarios:**
  - Si TTF: Fuente .ttf embebida (ej: Roboto Mono, Source Code Pro)
  - Si Bitmap: Nueva textura font_atlas.png de mayor resolución
- **Retrocompatibilidad:** Mantener API actual de dbgtxt

### 9. ⏳ Temas Dinámicos (Color Generativo)
**Descripción:** Sistema de generación procedural de temas de colores
**Prioridad:** Baja
**Estimación:** 4-6 horas
**Detalles:**
- **Objetivos:**
  - Gradiente de fondo variable (color base + variaciones automáticas)
  - Color de pelotas variable (monocromático, complementario, análogo, etc.)
  - Generación algorítmica de paletas armónicas
- **Implementación propuesta:**
  - **HSV Color Space:** Generar paletas en espacio HSV para control intuitivo
    - Hue (matiz): 0-360° para variación de color
    - Saturation (saturación): 0-100% para intensidad
    - Value (brillo): 0-100% para luminosidad
  - **Esquemas de color:**
    - Monocromático (un matiz + variaciones de saturación/brillo)
    - Complementario (matiz opuesto en rueda de color)
    - Análogo (matices adyacentes ±30°)
    - Triádico (3 matices equidistantes 120°)
    - Tetrádico (4 matices en cuadrado/rectángulo)
  - **Parámetros configurables:**
    - Base hue (0-360°): Color principal del tema
    - Saturation range (0-100%): Rango de intensidad
    - Value range (0-100%): Rango de brillo
    - Esquema de armonía: mono/complementario/análogo/etc.
    - Gradiente de fondo: Automático según base hue
  - **Controles de usuario:**
    - Tecla G: Generar nuevo tema aleatorio
    - Tecla Shift+G: Ciclar esquemas de armonía
    - Guardar temas generados favoritos (slot 8-12)
- **Algoritmos:**
  - **Gradiente de fondo:** Base hue → Variación análoga oscura (fondo inferior)
  - **Color de pelotas:** Según esquema elegido (complementario para contraste máximo)
  - **Conversión HSV → RGB:** Algoritmo estándar para SDL rendering
- **Ejemplos de temas generados:**
  - Tema "Cyberpunk": Base cyan (180°) + Complementario magenta (300°)
  - Tema "Autumn": Base naranja (30°) + Análogo rojo-amarillo
  - Tema "Ocean Deep": Base azul (240°) + Monocromático variaciones
  - Tema "Toxic": Base verde lima (120°) + Complementario púrpura
- **Persistencia:**
  - Guardar temas generados en config.ini (opcional)
  - Teclas 8-9-0 para slots de temas custom
- **Compatibilidad:**
  - No reemplaza temas existentes (1-7)
  - Modo adicional de selección de tema

---

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