coffee_crisis_arcade_edition/DELTATIME_MIGRATION_PLAN.md

Plan de Migración DeltaTime - Eliminación de frameFactor

Problema Identificado

Se están usando frameFactor conversions en 7 archivos, lo que indica una migración incompleta a deltaTime. El patrón float frameFactor = deltaTime / (1000.0f / 60.0f) simula frames de 60fps en lugar de usar tiempo real.

Archivos Afectados y Estado

1. balloon.cpp - 9 ocurrencias en métodos: moveX(), moveY(), updateState(), updateCreation()
2. balloon_manager.cpp - 2 ocurrencias en updateBalloonDeployment()
3. bullet.cpp - 3 ocurrencias en move()
4. item.cpp - 6 ocurrencias en move()
5. moving_sprite.cpp - 5 ocurrencias en move()
6. tabe.cpp - 5 ocurrencias en update() y updateHitEffect()
7. credits.cpp - 3 ocurrencias en update() y handleFadeOut()

Estrategia de Migración

Opción A: Velocidades ya en pixels/segundo

Si las velocidades están definidas en pixels/segundo:

// ANTES (incorrecto)
float frameFactor = deltaTime / (1000.0f / 60.0f);
pos_x_ += vel_x_ * frameFactor;

// DESPUÉS (correcto)
pos_x_ += vel_x_ * (deltaTime / 1000.0f);  // deltaTime en ms -> segundos

Opción B: Velocidades en pixels/frame (legacy)

Si las velocidades están en pixels/frame (sistema legacy):

// ANTES (incorrecto con deltaTime)
float frameFactor = deltaTime / (1000.0f / 60.0f);
pos_x_ += vel_x_ * frameFactor;

// OPCIÓN 1: Convertir velocidades a pixels/segundo
static constexpr float VEL_X_PER_SECOND = VEL_X_PER_FRAME * 60.0f;
pos_x_ += VEL_X_PER_SECOND * (deltaTime / 1000.0f);

// OPCIÓN 2: Mantener frame-factor pero mejorar claridad
pos_x_ += vel_x_ * (deltaTime / FRAME_TIME_MS);  // donde FRAME_TIME_MS = 16.67f

Plan de Ejecución

Fase 1: Análisis de Velocidades

• Revisar definiciones de velocidades en cada clase
• Determinar si están en pixels/frame o pixels/segundo
• Identificar constantes que necesitan conversión

Fase 2: Migración por Archivo

• balloon.cpp: Migrar velocidades x/y y contadores ✅
• balloon_manager.cpp: Migrar balloon_deploy_counter_ ✅
• bullet.cpp: Migrar velocidades de bala ✅ (VEL_Y: -3.0F→-0.18F, VEL_X: ±2.0F→±0.12F)
• item.cpp: Migrar física de ítems ✅ (vel_x: ±1.0F→±0.06F, vel_y: -4.0F→-0.24F, accel_y: 0.2F→0.012F)
• moving_sprite.cpp: Migrar sistema base de movimiento
• tabe.cpp: Migrar movimiento y efectos
• credits.cpp: Migrar contadores de timing

Fase 3: Verificación

• Compilar y probar cada archivo migrado
• Verificar que el comportamiento se mantiene consistente
• Eliminar todas las referencias a frameFactor
• Actualizar comentarios para reflejar unidades correctas

Criterios de Éxito

1. ✅ Cero ocurrencias de "frameFactor" en el código
2. ✅ Todas las velocidades claramente documentadas (pixels/segundo vs pixels/frame)
3. ✅ Comportamiento del juego idéntico al anterior
4. ✅ Código más limpio y mantenible

Notas Importantes

• El frameFactor actual simula 60fps: deltaTime / 16.67ms
• Esto significa que las velocidades actuales están en "pixels per 16.67ms"
• Para verdadero deltaTime, necesitamos convertir a "pixels per second" o usar factor de frame explícito
• Mantener constantes claras para evitar números mágicos

Estado: En Progreso

• Análisis iniciado
• Plan documentado
• Próximo paso: Análisis de velocidades en cada archivo