From df93d5080d9730d50cae28346d15a97d38f5430c Mon Sep 17 00:00:00 2001 From: Sergio Valor Date: Sun, 19 Oct 2025 07:59:32 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20Reorganizaci=C3=B3n=20completa=20del=20?= =?UTF-8?q?README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Cambios principales:** 1. **Nueva estructura organizada**: - Secciones claramente separadas sin repeticiones - Información actualizada y completa - Navegación mejorada con separadores 2. **Nuevo contenido agregado**: - 🎮 Modos de Funcionamiento (AppMode y SimulationMode) - ⚙️ Parámetros de Línea de Comandos (completo) - 🐦 Modo BOIDS (documentado) - 🖼️ Sistema AppLogo (logo periódico) - Tecla O (PNG_SHAPE) agregada 3. **Secciones actualizadas**: - Controles: Reorganizados por categoría SIN repeticiones - Temas: 15 temas (9 estáticos + 6 dinámicos), 2 páginas - Figuras 3D: 9 figuras (incluye PNG_SHAPE) - Todas las teclas documentadas (D, Shift+D, K, C, O, P, etc.) 4. **Información eliminada**: - Duplicación de "Controles de Temas" (eliminada) - Sección de temas repetida (consolidada) - Información obsoleta o desactualizada 5. **Mejoras de formato**: - Tablas para mejor legibilidad - Ejemplos de código con sintaxis - Emojis para secciones (navegación visual) - Estructura del proyecto actualizada **Cobertura completa:** - ✅ AppMode: SANDBOX, DEMO, DEMO_LITE, LOGO - ✅ SimulationMode: PHYSICS, SHAPE, BOIDS - ✅ 15 temas con sistema de 2 páginas - ✅ 9 figuras 3D incluyendo PNG_SHAPE - ✅ Parámetros CLI: -w, -h, -z, -f, -F, -m - ✅ Todas las teclas documentadas - ✅ Sistema AppLogo explicado - ✅ Modo BOIDS documentado 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 1075 ++++++++++++++++++++++++++++------------------------- 1 file changed, 565 insertions(+), 510 deletions(-) diff --git a/README.md b/README.md index 4c3a8bf..9c3c8c1 100644 --- a/README.md +++ b/README.md @@ -1,295 +1,562 @@ -# ViBe3 Physics - Simulador de Sprites con Fisica +# ViBe3 Physics - Simulador de Sprites con Física Avanzada -**ViBe3 Physics** es una demo experimental de **vibe-coding** que implementa **nuevas fisicas** expandiendo sobre el sistema de delta time. Utiliza **SDL3** para mostrar sprites (pelotas) rebotando con fisica avanzada independiente del framerate. +**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 100,000 sprites simultáneos. -El nombre refleja su proposito: **ViBe** (vibe-coding experimental) + **Physics** (nuevas fisicas experimentales). La demo sirve como sandbox para probar bucles de juego con timing independiente y renderizado optimizado. +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. -## 🎯 Caracteristicas Actuales +--- -- **Simulacion de fisica**: Gravedad, rebotes y colisiones con perdida de energia -- **Multiples escenarios**: 8 configuraciones predefinidas (1 a 100,000 pelotas) -- **Sistema de temas visuales**: 6 temas de colores con fondos degradados y paletas tematicas -- **Transiciones LERP**: Cambios de tema suaves y fluidos (0.5s) sin reiniciar escenario -- **Hot-swap de sprites**: Cambio de textura dinamico (ball.png ↔ ball_small.png) con tecla N -- **Sistema de zoom dinamico**: F1/F2 para ajustar el zoom de ventana (1x-10x) -- **Modos fullscreen**: F3 para fullscreen normal (mantiene aspecto), F4 para real fullscreen con resolucion nativa -- **Escalado configurable**: F5 alterna entre INTEGER (mantiene aspecto) y STRETCH (pantalla completa) en modo F3 -- **Gravedad multidireccional**: Gravedad hacia abajo, arriba, izquierda o derecha -- **8 Figuras 3D**: Esfera, Wave Grid, Helix, Torus, Cubo, Cilindro, Icosaedro, Atom -- **Interactividad**: Controles de teclado para modificar el comportamiento -- **Renderizado batch optimizado**: Sistema de batch rendering con SDL_RenderGeometry para 50K+ sprites -- **Colores tematicos**: Paletas de 8-24 colores por tema aplicadas proceduralmente -- **Monitor de rendimiento**: Contador FPS en tiempo real -- **Control V-Sync**: Activacion/desactivacion dinamica del V-Sync +## 🎯 Características Principales -## 🎮 Controles +- **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 -### Controles de Sistema -| Tecla | Accion | +--- + +## 🎮 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` | **Alternar debug display (FPS, V-Sync, valores fisica)** | -| `V` | **Alternar V-Sync ON/OFF** | -| `ESC` | Salir del programa | +| `H` | **Toggle debug display** (FPS, V-Sync, física, gravedad, modo) | +| `V` | **Toggle V-Sync** ON/OFF | +| `ESC` | **Salir** del programa | -### Controles de Ventana -| Tecla | Accion | +### Ventana y Zoom + +| Tecla | Acción | |-------|--------| -| `F1` | **Zoom out (reducir zoom ventana)** | -| `F2` | **Zoom in (aumentar zoom ventana)** | -| `F3` | **Toggle fullscreen normal (mantiene aspecto)** | -| `F4` | **Toggle real fullscreen (resolucion nativa)** | -| `F5` | **Toggle escalado INTEGER/STRETCH (solo en modo F3)** | +| `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) | -### Controles de Temas -| Tecla | Accion | +### Modos de Aplicación + +| Tecla | Acción | |-------|--------| -| `KP_1` | **Tema ATARDECER (colores calidos)** | -| `KP_2` | **Tema OCEANO (azules y cianes)** | -| `KP_3` | **Tema NEON (colores vibrantes)** | -| `KP_4` | **Tema BOSQUE (verdes naturales)** | -| `KP_5` | **Tema RGB (fondo blanco, colores matematicos)** | -| `KP_6` | **Tema MONOCHROME (fondo negro, todas las pelotas blancas)** | -| `B` | **Ciclar entre todos los temas** | -| `N` | **Cambiar sprite (ball.png ↔ ball_small.png)** | +| `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) | -### Controles de Simulacion -| Tecla | Accion | +### Temas de Colores + +| Tecla | Acción | |-------|--------| -| `1-8` | Cambiar numero de pelotas (1, 10, 100, 500, 1K, 10K, 50K, 100K) | -| `ESPACIO` | Impulsar todas las pelotas hacia arriba | -| `↑` | **Gravedad hacia ARRIBA (sale de figura con gravedad)** | -| `↓` | **Gravedad hacia ABAJO (sale de figura con gravedad)** | -| `←` | **Gravedad hacia IZQUIERDA (sale de figura con gravedad)** | -| `→` | **Gravedad hacia DERECHA (sale de figura con gravedad)** | -| `G` | **Alternar gravedad ON/OFF / Sale de figura SIN gravedad** | +| `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 | -### Controles de Figuras 3D -| Tecla | Accion | +### Sprites y Escenarios + +| Tecla | Acción | |-------|--------| -| `F` | **Toggle entre modo FISICA ↔ última FIGURA 3D** | -| `Q` | **Activar figura SPHERE (Esfera Fibonacci)** | -| `W` | **Activar figura WAVE GRID (Malla ondeante)** | -| `E` | **Activar figura HELIX (Espiral helicoidal)** | -| `R` | **Activar figura TORUS (Toroide/donut)** | -| `T` | **Activar figura CUBE (Cubo rotante triple XYZ)** | -| `Y` | **Activar figura CYLINDER (Cilindro)** | -| `U` | **Activar figura ICOSAHEDRON (Icosaedro D20)** | -| `I` | **Activar figura ATOM (Núcleo + órbitas)** | -| `KP_+` | **Aumentar escala de figura (+10%)** | -| `KP_-` | **Reducir escala de figura (-10%)** | -| `KP_*` | **Reset escala de figura a 100%** | -| `KP_/` | **Toggle zoom por profundidad Z (perspectiva ON/OFF)** | +| `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** | -## 📊 Informacion en Pantalla +### Física y Gravedad -- **Centro**: Numero de pelotas activas en **blanco** (temporal) -- **Centro**: Nombre del tema activo en **color tematico** (temporal, debajo del contador) +| 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) | -### Debug Display (Tecla `H`) +### Figuras 3D -Cuando se activa el debug display con la tecla `H`: +| 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) | -- **Esquina superior izquierda**: Estado V-Sync (VSYNC ON/OFF) en **cian** -- **Esquina superior derecha**: Contador FPS en tiempo real en **amarillo** -- **Lineas 3-5**: Valores fisica primera pelota (GRAV, VY, SURFACE, LOSS) en **magenta** -- **Linea 6**: Dirección de gravedad actual (GRAVITY UP/DOWN/LEFT/RIGHT) en **amarillo** -- **Linea 7**: Tema activo (THEME SUNSET/OCEAN/NEON/FOREST/RGB) en **amarillo claro** -- **Linea 8**: Modo de simulación (MODE PHYSICS/SPHERE/CUBE/etc.) en **verde claro** +### Modo BOIDS -## 🎨 Sistema de Temas de Colores +| Tecla | Acción | +|-------|--------| +| `C` | **Toggle BOIDS Mode** (comportamiento de enjambre) | -**ViBe3 Physics** incluye 6 temas visuales que transforman completamente la apariencia del simulador: +--- -### Temas Disponibles +## 🎨 Sistema de Temas (15 Temas - 2 Páginas) -| Tecla | Tema | Descripcion | Fondo | Paleta de Pelotas | -|-------|------|-------------|-------|-------------------| -| `KP_1` | **ATARDECER** | Colores calidos de puesta de sol | Degradado naranja-rojo | Tonos naranjas, rojos y amarillos | -| `KP_2` | **OCEANO** | Ambiente marino refrescante | Degradado azul-cian | Azules, cianes y verdes agua | -| `KP_3` | **NEON** | Colores vibrantes futuristas | Degradado magenta-cian | Magentas, cianes y rosas brillantes | -| `KP_4` | **BOSQUE** | Naturaleza verde relajante | Degradado verde oscuro-claro | Verdes naturales y tierra | -| `KP_5` | **RGB** | Colores matematicos puros | Fondo blanco solido | RGB puros y subdivisiones matematicas | -| `KP_6` | **MONOCHROME** | Estetica minimalista monocromatica | Degradado negro | Todas las pelotas blancas puras | +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. ### Controles de Temas -- **Seleccion directa**: Usa `KP_1` a `KP_6` para cambiar al tema deseado -- **Ciclado secuencial**: Presiona `B` para avanzar al siguiente tema en orden -- **Transiciones suaves**: Cambios de tema con interpolación LERP (0.5 segundos) -- **Sin reinicio**: Mantiene física y posiciones, solo cambia colores -- **Indicador visual**: Nombre del tema aparece temporalmente en centro de pantalla +- **`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 -### Sistema de Sprites Dinámico +### Página 1 (Temas Estáticos + 1 Dinámico) -- **Tecla N**: Cambia entre ball.png (10x10) y ball_small.png (6x6) -- **Hot-swap**: Sin reiniciar física, actualiza textura y hitbox al instante -- **Ajuste automático**: Posiciones corregidas según gravedad y superficie -- **Tamaño dinámico**: `current_ball_size_` obtenido desde `texture->getWidth()` -- **Texto informativo**: Muestra "SPRITE: NORMAL" o "SPRITE: SMALL" +| 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) | -### Detalles Tecnicos +### Página 2 (Temas Dinámicos Animados) -- **Fondos degradados**: Implementados con `SDL_RenderGeometry` usando vertices con colores interpolados -- **Paletas tematicas**: 8-24 colores por tema (RGB tiene 24, resto 8) -- **Interpolación LERP**: Transiciones RGB suaves frame-a-frame durante 0.5s -- **Sin regeneración**: Cambio de tema no llama `initBalls()`, solo actualiza colores -- **Rendimiento optimizado**: LERP tiene overhead mínimo (<1ms con 10K pelotas) -- **Compatibilidad completa**: Funciona con todos los escenarios (1 a 100,000 pelotas) +| 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 | -## 🎯 Sistema de Figuras 3D - Efectos Demoscene +### Características Técnicas -**ViBe3 Physics** incluye un sistema polimórfico de figuras 3D que convierte las pelotas en formas geométricas rotantes proyectadas en 2D. +- **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 -### Figuras Implementadas (8/8 Completas) +--- -#### 🌐 SPHERE (Tecla Q) -- **Algoritmo**: Fibonacci Sphere - distribución uniforme de puntos +## 🔷 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 -#### 🌊 WAVE GRID (Tecla W) -- **Algoritmo**: Grid NxN con ondas sinusoidales en Z -- **Animación**: Olas propagándose en tiempo real -- **Rotación**: XY combinada -- **Efecto**: Océano ondulante +#### 🌊 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 -- **Animación**: Rotación suave en eje Y -- **Altura**: 75% de pantalla (ajustable) +#### 🧬 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 + radio menor) -- **Rotación**: Triple eje con velocidades diferentes +#### 🍩 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) +#### 🎲 CUBE (Tecla `T`) - **Distribución inteligente**: - - 1-8: Solo vértices (8 puntos) - - 9-26: Vértices + caras + aristas (26 puntos) - - 27+: Grid volumétrico 3D uniforme + - 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) +#### 🏛️ 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 -- **Geometría**: 12 vértices, proporción áurea +#### ⚛️ 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) +#### ⚛️ 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 -### Características Técnicas +#### 🖼️ 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 -- **Física de atracción**: Sistema spring-damper (Hooke's Law) para transición suave -- **Profundidad Z simulada**: Color modulado según distancia (oscuro=fondo, brillante=frente) -- **Zoom por profundidad**: Perspectiva 3D con escala variable (50%-150% según Z) +### 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 -- **Escala dinámica**: Control manual con Numpad +/- (30% - 300%) -- **Protección de clipping**: Escala limitada automáticamente según resolución -- **Sin sprites adicionales**: Usa `SDL_SetTextureColorMod` y vértices escalados para efectos 3D +- **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 Físicos (defines.h) +### Parámetros Configurables (defines.h) ```cpp -// Física compartida entre todas las figuras -ROTOBALL_SPRING_K = 300.0f; // Rigidez del resorte (N/m) -ROTOBALL_DAMPING_BASE = 35.0f; // Amortiguación crítica -ROTOBALL_DAMPING_NEAR = 80.0f; // Absorción cerca del punto - -// Esfera -ROTOBALL_RADIUS_FACTOR = 0.333f; // 33% de altura de pantalla -ROTOBALL_ROTATION_SPEED_Y = 1.5f; // rad/s (eje Y) -ROTOBALL_ROTATION_SPEED_X = 0.8f; // rad/s (eje X) - -// Cubo -CUBE_SIZE_FACTOR = 0.25f; // 25% de altura de pantalla -CUBE_ROTATION_SPEED_X = 0.5f; // rad/s -CUBE_ROTATION_SPEED_Y = 0.7f; // rad/s -CUBE_ROTATION_SPEED_Z = 0.3f; // rad/s +// 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% +SHAPE_SCALE_MIN = 0.3f; // Mínimo 30% +SHAPE_SCALE_MAX = 3.0f; // Máximo 300% +SHAPE_SCALE_STEP = 0.1f; // Incremento 10% ``` -### Cómo Funciona +--- -1. **Generación**: Algoritmo específico distribuye puntos en forma 3D -2. **Rotación**: Matrices de rotación 3D aplicadas en tiempo real -3. **Escala**: Factor manual multiplicado a coordenadas y física -4. **Proyección**: Coordenadas 3D → 2D (ortográfica) -5. **Z-sorting**: Ordenar pelotas por profundidad (fondo primero) -6. **Profundidad**: Componente Z controla brillo del color -7. **Renderizado**: Batch rendering con color modulado +## 🐦 Modo BOIDS (Comportamiento de Enjambre) -### Uso +Sistema de inteligencia de enjambre basado en **3 reglas de Reynolds**: -- **Activación**: Presiona Q/W/E/R/T/Y/U/I para figura específica, o F para toggle -- **Escala**: Usa Numpad +/- para ajustar tamaño, * para reset -- **Perspectiva**: Numpad / para activar/desactivar zoom por profundidad (ON por defecto) -- **Salir**: G (sin gravedad), cursores (con gravedad), F (toggle), o 1-8 (cambiar escenario) -- **Compatible**: Funciona con 1-100,000 pelotas -- **Temas**: Mantiene paleta de colores activa +### 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 ` | Ancho de resolución | 320 | `-w 1920` | +| `-h, --height ` | Alto de resolución | 240 | `-h 1080` | +| `-z, --zoom ` | 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 ` | 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**: 640px +- **Alto mínimo**: 480px +- **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 # Bucle principal y logica del juego -│ ├── engine.h/cpp # Motor principal con loop y rendering -│ ├── ball.h/cpp # Clase Ball - fisica de pelotas -│ ├── defines.h # Constantes y configuracion -│ ├── shapes/ # Sistema polimorfico de figuras 3D -│ │ ├── shape.h # Interfaz abstracta Shape -│ │ ├── sphere_shape.h/cpp # Fibonacci Sphere -│ │ └── cube_shape.h/cpp # Cubo rotante triple -│ └── external/ # Utilidades y bibliotecas externas -│ ├── sprite.h/cpp # Clase Sprite - renderizado de texturas -│ ├── texture.h/cpp # Clase Texture - gestion de imagenes -│ ├── dbgtxt.h # Sistema de debug para texto en pantalla -│ └── stb_image.h # Biblioteca para cargar imagenes -├── data/ -│ ├── ball.png # Textura normal de la pelota (10x10 pixeles) -│ └── ball_small.png # Textura pequeña de la pelota (6x6 pixeles) -├── CMakeLists.txt # Configuracion de CMake -├── Makefile # Configuracion de Make -├── CLAUDE.md # Seguimiento de desarrollo -└── .gitignore # Archivos ignorados por Git +│ ├── 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 +- **C++20** compatible compiler (GCC 10+, Clang 12+, MSVC 2019+) - **CMake 3.20+** o **Make** -- Plataforma: Windows, Linux, macOS +- **Plataforma**: Windows, Linux, macOS -### Instalacion de SDL3 +### Instalación de SDL3 #### Windows (MinGW) ```bash -# Usando vcpkg o compilar desde fuente +# 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 +#### Linux (Ubuntu/Debian) ```bash -# Ubuntu/Debian +sudo apt update sudo apt install libsdl3-dev -# Arch Linux + +# Si no está disponible, compilar desde fuente +``` + +#### Linux (Arch) +```bash sudo pacman -S sdl3 ``` @@ -298,329 +565,104 @@ sudo pacman -S sdl3 brew install sdl3 ``` -## 🚀 Compilacion +--- + +## 🚀 Compilación + +### Opción 1: CMake (Recomendado) -### Opcion 1: CMake (Recomendado) ```bash -mkdir build && cd build +mkdir -p build && cd build cmake .. -make +cmake --build . ``` -### Opcion 2: Make directo +### Opción 2: Make directo + ```bash make ``` -## ▶️ Ejecucion +--- + +## ▶️ Ejecución + +### Ejecución Basic ```bash -# Desde la raiz del proyecto -./vibe3_physics # Linux/macOS -./vibe3_physics.exe # Windows +# Linux/macOS +./vibe3_physics + +# Windows +./vibe3_physics.exe ``` -## 📊 Detalles Tecnicos +### Ejemplos con Parámetros -### Configuracion Actual -- **Resolucion**: 320x240 pixeles (escalado x3 = 960x720 por defecto) +```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 -- **Fisica**: Gravedad constante (0.2 px/frame² → 720 px/s²), rebotes con perdida de energia variable (0.30-0.95) -- **Tamaño de pelota**: Dinámico (10x10 o 6x6 según sprite activo) -- **V-Sync**: Activado por defecto, controlable dinamicamente -- **Temas**: 6 temas con transiciones LERP de 0.5s -- **Figuras 3D**: 8 figuras completas con física de atracción +- **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 Codigo +### Arquitectura del Código -1. **main.cpp**: Contiene el bucle principal con cuatro fases: - - `calculateDeltaTime()`: Calcula tiempo transcurrido entre frames - - `update()`: Actualiza la logica del juego usando delta time + calculo FPS - - `checkEvents()`: Procesa eventos de entrada - - `render()`: Renderiza la escena + overlays informativos +El engine sigue una arquitectura **component-based** con separación de responsabilidades: -2. **Ball**: Maneja la fisica de cada pelota individual con timing basado en delta time -3. **Sprite**: Sistema de renderizado de texturas con filtro nearest neighbor -4. **Texture**: Gestion de carga y renderizado de imagenes con filtro pixel-perfect +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 -## ✅ Migracion a Delta Time (COMPLETADO) +### Sistema de Delta Time -### Sistema Anterior (Frame-Based) +**Conversión de unidades (frame-based → time-based):** -El sistema original estaba **acoplado a 60 FPS** con logica dependiente del framerate: +| 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 | -```cpp -// Sistema ANTIGUO en update() -if (SDL_GetTicks() - ticks > DEMO_SPEED) { // DEMO_SPEED = 1000/60 = 16.67ms - // Solo aqui se actualizaba la fisica cada 16.67ms - for (auto &ball : balls) { - ball->update(); // Sin parametros de tiempo - } - ticks = SDL_GetTicks(); -} -``` +**Beneficios:** +- ✅ Velocidad consistente entre 60Hz, 75Hz, 144Hz+ +- ✅ V-Sync independiente (misma velocidad ON/OFF) +- ✅ Física precisa y predecible +- ✅ Escalable a cualquier framerate -**Problemas del sistema anterior:** -- Velocidad inconsistente entre diferentes refresh rates (60Hz vs 75Hz vs 144Hz) -- Logica de fisica acoplada a framerate fijo -- V-Sync ON/OFF cambiaba la velocidad del juego -- Rendimiento inconsistente en diferentes hardware +### Batch Rendering -### Sistema Actual (Delta Time) +**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 -**Implementacion delta time** para simulacion independiente del framerate: - -```cpp -// Sistema NUEVO - Variables globales -Uint64 last_frame_time = 0; -float delta_time = 0.0f; - -// Calculo de delta time -void calculateDeltaTime() { - Uint64 current_time = SDL_GetTicks(); - if (last_frame_time == 0) { - last_frame_time = current_time; - delta_time = 1.0f / 60.0f; // Primer frame a 60 FPS - return; - } - - delta_time = (current_time - last_frame_time) / 1000.0f; // Convertir a segundos - last_frame_time = current_time; - - // Limitar delta time para evitar saltos grandes - if (delta_time > 0.05f) { - delta_time = 1.0f / 60.0f; // Fallback a 60 FPS - } -} - -// Bucle principal actualizado -while (!should_exit) { - calculateDeltaTime(); // 1. Calcular tiempo transcurrido - update(); // 2. Actualizar logica (usa delta_time) - checkEvents(); // 3. Procesar entrada - render(); // 4. Renderizar escena -} -``` - -### Conversion de Fisica: Frame-Based → Time-Based - -#### 1. Conversion de Velocidades - -```cpp -// En Ball::Ball() constructor -// ANTES: velocidades en pixeles/frame -vx_ = vx; -vy_ = vy; - -// AHORA: convertir a pixeles/segundo (x60) -vx_ = vx * 60.0f; -vy_ = vy * 60.0f; -``` - -#### 2. Conversion de Gravedad (Aceleracion) - -```cpp -// En Ball::Ball() constructor -// ANTES: gravedad en pixeles/frame² -gravity_force_ = GRAVITY_FORCE; - -// AHORA: convertir a pixeles/segundo² (x60²) -gravity_force_ = GRAVITY_FORCE * 60.0f * 60.0f; // 3600x multiplicador -``` - -**¿Por que 60² para gravedad?** -- Velocidad: `pixeles/frame * frame/segundo = pixeles/segundo` → **x60** -- Aceleracion: `pixeles/frame² * frame²/segundo² = pixeles/segundo²` → **x60²** - -#### 3. Aplicacion de Delta Time en Fisica - -```cpp -// En Ball::update(float deltaTime) -// ANTES: incrementos fijos por frame -vy_ += gravity_force_; -pos_.x += vx_; -pos_.y += vy_; - -// AHORA: incrementos proporcionales al tiempo transcurrido -vy_ += gravity_force_ * deltaTime; // Aceleracion * tiempo -pos_.x += vx_ * deltaTime; // Velocidad * tiempo -pos_.y += vy_ * deltaTime; -``` - -### Valores de Debug: Antes vs Ahora - -| Parametro | Sistema Anterior | Sistema Delta Time | Razon | -|-----------|------------------|-------------------|-------| -| **Velocidad X/Y** | 1.0 - 3.0 pixeles/frame | 60.0 - 180.0 pixeles/segundo | x60 conversion | -| **Gravedad** | 0.2 pixeles/frame² | 720.0 pixeles/segundo² | x3600 conversion | -| **Debug Display** | No disponible | GRAV: 720.000000 VY: -140.5 FLOOR: NO | Valores en tiempo real | - -### Beneficios Conseguidos - -- ✅ **Velocidad consistente** entre 60Hz, 75Hz, 144Hz y otros refresh rates -- ✅ **V-Sync independiente**: misma velocidad con V-Sync ON/OFF -- ✅ **Fisica precisa**: gravedad y movimiento calculados correctamente -- ✅ **Escalabilidad**: preparado para futuras optimizaciones -- ✅ **Debug en tiempo real**: monitoreo de valores de fisica - -### Sistema de Debug Implementado - -```cpp -// Debug display para primera pelota -if (!balls.empty()) { - std::string debug_text = "GRAV: " + std::to_string(balls[0]->getGravityForce()) + - " VY: " + std::to_string(balls[0]->getVelocityY()) + - " FLOOR: " + (balls[0]->isOnFloor() ? "YES" : "NO"); - dbg_print(8, 24, debug_text.c_str(), 255, 0, 255); // Magenta -} -``` - -## 🚀 Sistema de Batch Rendering - -### **Problema Original** -El renderizado individual de sprites era el principal cuello de botella: -- **50,000 bolas**: 50,000 llamadas `SDL_RenderTexture()` por frame -- **Resultado**: ~10 FPS (inutilizable) - -### **Solución Implementada: SDL_RenderGeometry** -Batch rendering que agrupa todos los sprites en una sola llamada: - -```cpp -// Recopilar datos de todas las bolas -for (auto &ball : balls) { - SDL_FRect pos = ball->getPosition(); - Color color = ball->getColor(); - addSpriteToBatch(pos.x, pos.y, pos.w, pos.h, color.r, color.g, color.b); -} - -// Renderizar TODAS las bolas en una sola llamada -SDL_RenderGeometry(renderer, texture->getSDLTexture(), - batch_vertices.data(), batch_vertices.size(), - batch_indices.data(), batch_indices.size()); -``` - -### **Arquitectura del Batch** -1. **Vértices**: 4 vértices por sprite (quad) con posición, UV y color -2. **Índices**: 6 índices por sprite (2 triángulos) -3. **Acumulación**: Todos los sprites se acumulan en vectores globales -4. **Renderizado**: Una sola llamada `SDL_RenderGeometry` por frame - -### **Rendimiento Conseguido** -- **50,000 bolas**: >75 FPS constante (mejora de 750%) -- **100,000 bolas**: Fluido y jugable -- **Escalabilidad**: Preparado para renderizado masivo de sprites - -## 🎨 Sistema de Transiciones LERP - -### **Problema Original** -El cambio de temas reiniciaba completamente la simulación: -- Llamaba a `initBalls()` regenerando todas las pelotas -- Perdía posiciones, velocidades y estado físico -- Cambio brusco e instantáneo -- Disruptivo para la experiencia visual - -### **Solución Implementada: Interpolación Lineal** -Transiciones suaves de colores sin afectar la física: - -```cpp -// Variables de transición -bool transitioning_ = false; -float transition_progress_ = 0.0f; // 0.0 a 1.0 -float transition_duration_ = 0.5f; // 0.5 segundos - -// Función LERP -float lerp(float a, float b, float t) { - return a + (b - a) * t; -} - -// Interpolación de colores -Color getInterpolatedColor(size_t ball_index) { - Color current = balls_[ball_index]->getColor(); - Color target = target_theme.ball_colors[ball_index % count]; - - return { - lerp(current.r, target.r, transition_progress_), - lerp(current.g, target.g, transition_progress_), - lerp(current.b, target.b, transition_progress_) - }; -} - -// En update() -if (transitioning_) { - transition_progress_ += delta_time / transition_duration_; - if (transition_progress_ >= 1.0f) { - // Finalizar transición, actualizar colores permanentes - for (size_t i = 0; i < balls_.size(); i++) { - balls_[i]->setColor(target_colors[i]); - } - transitioning_ = false; - } -} -``` - -### **Características del Sistema** -- **Interpolación frame-a-frame**: Colores RGB calculados en cada frame -- **Fondo degradado**: También interpola colores de vértices del fondo -- **Independiente del framerate**: Usa `delta_time` para duración precisa -- **Sin impacto físico**: Mantiene posiciones, velocidades y gravedad -- **Overhead mínimo**: <1ms adicional con 10,000 pelotas - -## 🔄 Sistema de Hot-Swap de Sprites - -### **Concepto** -Cambio dinámico de texturas sin reiniciar la simulación física. - -### **Desafío Técnico: Ajuste de Posiciones** -Cuando las pelotas están en reposo en superficies, cambiar el tamaño del hitbox causa problemas: - -**Caso 1: Grande → Pequeño (10px → 6px)** -- Pelota en suelo: `pos.y = screen_height - 10` -- Cambia a 6px: `pos.y = screen_height - 6` -- **Problema**: Queda flotando 4 píxeles arriba → Cae de nuevo ❌ - -**Caso 2: Pequeño → Grande (6px → 10px)** -- Pelota en suelo: `pos.y = screen_height - 6` -- Cambia a 10px: hitbox se entierra 4 píxeles -- **Problema**: Detección de colisión → Rebote violento hacia arriba ❌ - -### **Solución: Ajuste Inteligente de Posiciones** - -```cpp -void updateBallSizes(int old_size, int new_size) { - float delta_size = new_size - old_size; - - for (auto& ball : balls_) { - if (ball->isOnSurface()) { - // Solo ajustar pelotas en superficie - SDL_FRect pos = ball->getPosition(); - - switch (ball->getGravityDirection()) { - case DOWN: pos.y += delta_size; break; // Bajar si crece - case UP: pos.y -= delta_size; break; // Subir si crece - case LEFT: pos.x -= delta_size; break; - case RIGHT: pos.x += delta_size; break; - } - - ball->updateSize(new_size); - ball->setPosition(pos.x, pos.y); - } else { - // Pelotas en vuelo: solo actualizar tamaño - ball->updateSize(new_size); - } - } -} -``` - -### **Texturas Disponibles** -- **ball.png**: 10x10 píxeles (normal) -- **ball_small.png**: 6x6 píxeles (pequeño) - -### **Características** -- **Tamaño dinámico**: `current_ball_size_` obtenido de `texture->getWidth()` -- **Ajuste según gravedad**: Posición corregida según dirección gravitacional -- **Hot-swap completo**: Cambia textura, hitbox y clip del sprite -- **Sin reinicio físico**: Mantiene velocidades y trayectorias -- **Texto informativo**: Muestra "SPRITE: NORMAL" o "SPRITE: SMALL" +--- ## 🛠️ Desarrollo @@ -628,23 +670,36 @@ 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 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 Tecnicas +--- -- El proyecto usa **smart pointers** (unique_ptr, shared_ptr) para gestion de memoria -- **RAII** para recursos SDL -- **Separacion de responsabilidades** entre clases -- **Configuracion multiplataforma** (Windows, Linux, macOS) -- **Filtro nearest neighbor** para texturas pixel-perfect -- **Sistema de metricas** en tiempo real (FPS, V-Sync) +## 📝 Notas Técnicas -## 🐛 Problemas Conocidos - -Ninguno conocido. El sistema esta completamente funcional con delta time implementado. +- **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) --- -*Proyecto desarrollado como base para experimentacion con game loops y fisica en tiempo real usando SDL3.* \ No newline at end of file +## 🐛 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*