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