🖐️ Finger Dance

Portal de Ritmo por Gestos Dinámicos desarrollado con WebGPU, MediaPipe y el entorno nativo de Electrobun.

Finger Dance es un videojuego de ritmo premium de alto rendimiento diseñado para ejecutarse en el escritorio a través de una ventana nativa súper liviana impulsada por Electrobun (WebView2 en Windows). El juego procesa mapas de ritmo dinámicos en tiempo real, renderiza gráficos 3D acelerados por hardware con WebGPU y sigue el movimiento de tus dedos mediante la cámara web utilizando MediaPipe Tasks Vision.

---

✨ Características Destacadas

• ⚡ Gráficos de Próxima Generación (WebGPU): Motor gráfico 3D nativo escrito desde cero en WebGPU, utilizando sombreadores de alto rendimiento para carriles de curvas Catmull-Rom, notas dinámicas y efectos de partículas fluidos.
• 🖐️ Seguimiento de Manos Inteligente (MediaPipe): Detección y seguimiento tridimensional de las yemas de tus dedos índice en tiempo real con latencia ultra baja.
• 🔒 Concesión de Permisos Silenciosa: Configuración avanzada en el proceso host de Windows que inyecta automáticamente los argumentos de WebView2 (--use-fake-ui-for-media-stream) para otorgar acceso seguro a la cámara web al instante sin molestas alertas emergentes.
• 📦 Cargador Dinámico de Mapas ZIP: Arrastra y suelta directamente tus niveles personalizados en formato .zip. El juego descomprime, valida, extrae el archivo de audio .mp3, parsea las dificultades de notas (info.json, Hard.json, etc.) y renderiza las carátulas en tiempo real.
• 📊 Minimapa Canvas 2D de Alta Densidad: Un panel interactivo optimizado que dibuja miles de ticks y notas vectoriales en un <canvas> ajustado al devicePixelRatio del monitor, eliminando por completo la sobrecarga de reconciliación del DOM de React.
• 🚀 Algoritmos de Alto Rendimiento:
  • Búsqueda Binaria ($O(\log N)$): Localización instantánea de notas visibles y carriles en el bucle de renderizado WebGPU al avanzar, retroceder o pausar la pista.
  • Punteros Secuenciales ($O(1)$): Spawn y procesamiento secuencial de notas en tiempo real para evitar picos de latencia.
  • Liberación Activa de GPU: Destrucción explícita de búferes de GPU (uniformBuffer, noteStorageBuffer, etc.) al desmontar elementos para evitar fugas de memoria.

---

🛠️ Requisitos Previos

• Bun: Entorno de ejecución rápido de JavaScript para la ejecución de scripts y dependencias.
• Navegador/Sistema compatible con WebGPU: Se requiere soporte de WebGPU en el sistema operativo (Edge/Chromium actualizado).

---

🚀 Instalación y Ejecución

Sigue estos sencillos pasos para arrancar el entorno de desarrollo:

1. Clonar el repositorio e instalar dependencias

Instala los módulos de Node de manera ultra veloz usando bun:

bun install

2. Iniciar el servidor de desarrollo (Vite HMR)

En una terminal secundaria, arranca el servidor de desarrollo Vite con Hot Module Replacement (HMR) en el puerto 3000:

bun run dev:hmr

3. Lanzar la aplicación nativa (Electrobun)

En tu terminal principal, compila y lanza la ventana nativa de escritorio:

bun run start

¡Nota: En modo desarrollo se abrirán automáticamente las Herramientas de Desarrollador (DevTools) al lado del juego para que puedas inspeccionar los logs de WebGPU y MediaPipe en vivo!

---

📂 Estructura del Proyecto

├── src/
│   ├── bun/
│   │   └── index.ts          # Proceso principal (Host) de Electrobun (Configuración de ventana y permisos)
│   ├── mainview/
│   │   ├── App.tsx           # Vista y portal principal (Splash screen, selector de mapa y juego)
│   │   ├── WebGPUCanvas.tsx  # Motor de renderizado en WebGPU y lógica del bucle de juego
│   │   ├── NoteManager.ts    # Gestor y cálculos de splines y spawns de notas en O(log N)
│   │   ├── BeatmapDashboard.tsx # Panel lateral de estadísticas y minimapa en Canvas 2D
│   │   ├── PlayerControls.tsx   # Controles inferiores (Reproducción, reinicio y barra de progreso)
│   │   └── SongHeader.tsx    # Cabecera de metadatos de la canción y tiempo
│   └── index.html            # Plantilla base del Frontend
├── electrobun.config.ts      # Configuración de compilación e HMR de Electrobun
├── package.json              # Definición de dependencias y scripts de Bun
└── tsconfig.json             # Configuración del compilador TypeScript

---

🎮 Cómo Jugar

1. Al iniciar el juego, verás una pantalla de bienvenida que te invita a cargar un mapa.
2. Arrastra y suelta cualquier archivo .zip de un nivel compatible (estilo Dance Dash).
3. Elige la dificultad deseada de la lista generada dinámicamente y haz clic en Iniciar Secuencia.
4. Alinea tu mano frente a la cámara y usa tus dedos índice para golpear las esferas, seguir las líneas de ritmo y esquivar las trampas.
5. Usa el control deslizante de Ancho en la barra inferior para ajustar la escala del campo de juego a tu gusto.

---

📄 Licencia

Este proyecto está bajo la licencia MIT. Siéntete libre de clonarlo, modificarlo y compartir tus propias mejoras para hacer de Finger Dance la mejor experiencia rítmica en WebGPU.