vibe3_physics/REFACTOR_PLAN.md

# Plan de Refactorización - ViBe3 Physics Engine

## Objetivo
Aplicar el **Principio de Responsabilidad Única (SRP)** al motor Engine para:
- Mejorar mantenibilidad del código
- Facilitar extensión de funcionalidades
- Reducir acoplamiento entre sistemas
- Hacer el código más testeable

## Métricas Iniciales (Pre-refactorización)
- **engine.cpp**: 2341 líneas
- **engine.h**: 196 líneas con 40+ miembros privados
- **Responsabilidades mezcladas**: 7 subsistemas en una sola clase

## Progreso de Refactorización

### ✅ FASE 1: InputHandler (COMPLETADA)
**Fecha**: 10/01/2025
**Commit**: (pendiente)

**Impacto**: ~430 líneas extraídas del `handleEvents()`

**Archivos creados**:
- `source/input/input_handler.h`
- `source/input/input_handler.cpp`

**Métodos públicos agregados a Engine (24 total)**:
```cpp
// Gravedad y física
void pushBallsAwayFromGravity();
void handleGravityToggle();
void handleGravityDirectionChange(GravityDirection, const char*);

// Display y depuración
void toggleVSync();
void toggleDebug();

// Figuras 3D
void toggleShapeMode();
void activateShape(ShapeType, const char*);
void handleShapeScaleChange(bool);
void resetShapeScale();
void toggleDepthZoom();

// Temas de colores
void cycleTheme(bool);
void switchThemeByNumpad(int);
void toggleThemePage();
void pauseDynamicTheme();

// Sprites/Texturas
void switchTexture();

// Escenarios
void changeScenario(int, const char*);

// Zoom y fullscreen
void handleZoomIn();
void handleZoomOut();
void toggleFullscreen();
void toggleRealFullscreen();
void toggleIntegerScaling();

// Modos de aplicación
void toggleDemoMode();
void toggleDemoLiteMode();
void toggleLogoMode();
```

**Cambios internos**:
- Métodos internos renombrados con sufijo `Internal`:
  - `toggleShapeMode()` → `toggleShapeModeInternal()`
  - `activateShape()` → `activateShapeInternal()`
  - `switchTexture()` → `switchTextureInternal()`
- Eliminado método `handleEvents()` (420 líneas)
- Bucle `run()` simplificado a 12 líneas

**Beneficios**:
- ✅ Engine desacoplado de eventos SDL
- ✅ InputHandler stateless (fácilmente testeable)
- ✅ Clara separación entre detección de input y ejecución de lógica
- ✅ Compilación exitosa sin errores

---

### 🔄 FASE 2: SceneManager (PENDIENTE)
**Impacto estimado**: ~500 líneas + `std::vector<Ball>` movido

**Responsabilidad**: Crear, actualizar y gestionar todas las `Ball`

**Miembros a mover**:
- `std::vector<std::unique_ptr<Ball>> balls_`
- `GravityDirection current_gravity_`
- `int scenario_`

**Métodos a mover**:
- `initBalls()`
- `pushBallsAwayFromGravity()`
- `switchBallsGravity()`
- `enableBallsGravityIfDisabled()`
- `forceBallsGravityOn() / Off()`
- `changeGravityDirection()`
- `updateBallSizes()`

---

### 🔄 FASE 3: UIManager (PENDIENTE)
**Impacto estimado**: ~300 líneas + rendering de texto movido

**Responsabilidad**: Renderizar y actualizar interfaz de usuario

**Miembros a mover**:
- `Notifier notifier_`
- `TextRenderer text_renderer_debug_`
- `bool show_debug_`
- Variables FPS (`fps_frame_count_`, `fps_current_`, `fps_text_`, `vsync_text_`)

**Métodos a mover**:
- `showNotificationForAction()`
- Renderizado de FPS, debug info, gravedad, tema, modo

---

### 🔄 FASE 4: StateManager (PENDIENTE)
**Impacto estimado**: ~600 líneas de lógica compleja

**Responsabilidad**: Gestionar máquina de estados (DEMO/LOGO/SANDBOX)

**Miembros a mover**:
- `AppMode current_app_mode_, previous_app_mode_`
- Variables DEMO (`demo_timer_`, `demo_next_action_time_`)
- Variables LOGO (todas las relacionadas con logo mode)

**Métodos a mover**:
- `setState()`
- `updateDemoMode()`
- `performDemoAction()`
- `randomizeOnDemoStart()`
- `enterLogoMode() / exitLogoMode()`

---

### 🔄 FASE 5: ShapeManager (PENDIENTE)
**Impacto estimado**: ~400 líneas + lógica de shapes

**Responsabilidad**: Crear, actualizar y renderizar figuras 3D polimórficas

**Miembros a mover**:
- `SimulationMode current_mode_`
- `ShapeType current_shape_type_, last_shape_type_`
- `std::unique_ptr<Shape> active_shape_`
- `float shape_scale_factor_`
- `bool depth_zoom_enabled_`

**Métodos a mover**:
- `toggleShapeModeInternal()`
- `activateShapeInternal()`
- `updateShape()`
- `generateShape()`
- `clampShapeScale()`

---

### 🔄 FASE 6: Limpieza y Consolidación Final (PENDIENTE)
**Impacto esperado**: Engine reducido a ~400 líneas (coordinador)

**Tareas**:
1. Limpiar `engine.h` / `engine.cpp` de código legacy
2. Verificar que todos los sistemas están correctamente integrados
3. Documentar interfaz pública de Engine
4. Actualizar `CLAUDE.md` con nueva arquitectura
5. Verificar compilación y funcionamiento completo

---

## Arquitectura Final Esperada

```cpp
class Engine {
private:
    // SDL Core
    SDL_Window* window_;
    SDL_Renderer* renderer_;

    // Componentes (composición)
    std::unique_ptr<InputHandler> input_handler_;
    std::unique_ptr<SceneManager> scene_manager_;
    std::unique_ptr<UIManager> ui_manager_;
    std::unique_ptr<StateManager> state_manager_;
    std::unique_ptr<ShapeManager> shape_manager_;
    std::unique_ptr<ThemeManager> theme_manager_;

    // Estado mínimo
    bool should_exit_;
    float delta_time_;

public:
    void run() {
        while (!should_exit_) {
            calculateDeltaTime();
            input_handler_->process(*this);
            update();
            render();
        }
    }
};
```

## Notas
- Cada fase incluye su propio **commit atómico**
- Las fases son **secuenciales** (cada una depende de la anterior)
- Se preserva **100% de funcionalidad** en cada fase
- Compilación verificada después de cada commit

---

*Documento de seguimiento para refactorización ViBe3 Physics*
*Última actualización: 2025-01-10 - Fase 1 completada*