710 lines
25 KiB
Markdown
710 lines
25 KiB
Markdown
# ViBe3 Physics - Simulador de Sprites con Física Avanzada
|
||
|
||
**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 50,000 sprites simultáneos.
|
||
|
||
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
## 🎯 Características Principales
|
||
|
||
- **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
|
||
|
||
---
|
||
|
||
## 🎮 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` | **Toggle debug display** (FPS, V-Sync, física, gravedad, modo) |
|
||
| `V` | **Toggle V-Sync** ON/OFF |
|
||
| `ESC` | **Salir** del programa |
|
||
|
||
### Ventana y Zoom
|
||
|
||
| Tecla | Acción |
|
||
|-------|--------|
|
||
| `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) |
|
||
|
||
### Modos de Aplicación
|
||
|
||
| Tecla | Acción |
|
||
|-------|--------|
|
||
| `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) |
|
||
|
||
### Temas de Colores
|
||
|
||
| Tecla | Acción |
|
||
|-------|--------|
|
||
| `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 |
|
||
|
||
### Sprites y Escenarios
|
||
|
||
| Tecla | Acción |
|
||
|-------|--------|
|
||
| `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** |
|
||
|
||
### Física y Gravedad
|
||
|
||
| 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) |
|
||
|
||
### Figuras 3D
|
||
|
||
| 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) |
|
||
|
||
### Modo BOIDS
|
||
|
||
| Tecla | Acción |
|
||
|-------|--------|
|
||
| `C` | **Toggle BOIDS Mode** (comportamiento de enjambre) |
|
||
|
||
---
|
||
|
||
## 🎨 Sistema de Temas (15 Temas - 2 Páginas)
|
||
|
||
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
|
||
|
||
- **`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
|
||
|
||
### Página 1 (Temas Estáticos + 1 Dinámico)
|
||
|
||
| 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) |
|
||
|
||
### Página 2 (Temas Dinámicos Animados)
|
||
|
||
| 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 |
|
||
|
||
### Características Técnicas
|
||
|
||
- **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
|
||
|
||
---
|
||
|
||
## 🔷 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
|
||
|
||
#### 🌊 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 (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 + menor)
|
||
- **Rotación**: Triple eje (X, Y, Z) con velocidades diferentes
|
||
- **Efecto**: Donut flotante estilo demoscene
|
||
|
||
#### 🎲 CUBE (Tecla `T`)
|
||
- **Distribución inteligente**:
|
||
- 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`)
|
||
- **Algoritmo**: Cilindro con tapas circulares
|
||
- **Rotación**: Eje Y (spin horizontal)
|
||
- **Efecto**: Columna griega rotante
|
||
|
||
#### ⚛️ 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`)
|
||
- **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
|
||
|
||
#### 🖼️ 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
|
||
|
||
### 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
|
||
- **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 Configurables (defines.h)
|
||
|
||
```cpp
|
||
// 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%
|
||
```
|
||
|
||
---
|
||
|
||
## 🐦 Modo BOIDS (Comportamiento de Enjambre)
|
||
|
||
Sistema de inteligencia de enjambre basado en **3 reglas de Reynolds**:
|
||
|
||
### 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 <px>` | Ancho de resolución | 320 | `-w 1920` |
|
||
| `-h, --height <px>` | Alto de resolución | 240 | `-h 1080` |
|
||
| `-z, --zoom <n>` | 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 <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**: 320px
|
||
- **Alto mínimo**: 240px
|
||
- **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 # 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 (GCC 10+, Clang 12+, MSVC 2019+)
|
||
- **CMake 3.20+** o **Make**
|
||
- **Plataforma**: Windows, Linux, macOS
|
||
|
||
### Instalación de SDL3
|
||
|
||
#### Windows (MinGW)
|
||
```bash
|
||
# 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 (Ubuntu/Debian)
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install libsdl3-dev
|
||
|
||
# Si no está disponible, compilar desde fuente
|
||
```
|
||
|
||
#### Linux (Arch)
|
||
```bash
|
||
sudo pacman -S sdl3
|
||
```
|
||
|
||
#### macOS
|
||
```bash
|
||
brew install sdl3
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Compilación
|
||
|
||
### Opción 1: CMake (Recomendado)
|
||
|
||
```bash
|
||
mkdir -p build && cd build
|
||
cmake ..
|
||
cmake --build .
|
||
```
|
||
|
||
### Opción 2: Make directo
|
||
|
||
```bash
|
||
make
|
||
```
|
||
|
||
---
|
||
|
||
## ▶️ Ejecución
|
||
|
||
### Ejecución Basic
|
||
|
||
```bash
|
||
# Linux/macOS
|
||
./vibe3_physics
|
||
|
||
# Windows
|
||
./vibe3_physics.exe
|
||
```
|
||
|
||
### Ejemplos con Parámetros
|
||
|
||
```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
|
||
- **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 Código
|
||
|
||
El engine sigue una arquitectura **component-based** con separación de responsabilidades:
|
||
|
||
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
|
||
|
||
### Sistema de Delta Time
|
||
|
||
**Conversión de unidades (frame-based → time-based):**
|
||
|
||
| 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 |
|
||
|
||
**Beneficios:**
|
||
- ✅ Velocidad consistente entre 60Hz, 75Hz, 144Hz+
|
||
- ✅ V-Sync independiente (misma velocidad ON/OFF)
|
||
- ✅ Física precisa y predecible
|
||
- ✅ Escalable a cualquier framerate
|
||
|
||
### Batch Rendering
|
||
|
||
**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
|
||
|
||
---
|
||
|
||
## 🛠️ Desarrollo
|
||
|
||
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 característica'`)
|
||
4. Push a la rama (`git push origin feature/nueva-caracteristica`)
|
||
5. Crear Pull Request
|
||
|
||
---
|
||
|
||
## 📝 Notas Técnicas
|
||
|
||
- **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)
|
||
|
||
---
|
||
|
||
## 🐛 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*
|