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):

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

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