WebViewer

LoveBeat Tools - WebViewer

El LoveBeat WebViewer es una herramienta interactiva diseñada para explorar, visualizar en 3D y animar los recursos del juego LoveBeat directamente desde el navegador, sin necesidad de abrir el cliente del juego.

La finalidad de este proyecto es proveer un entorno visual donde se puedan probar combinaciones de ropa, inspeccionar modelos 3D y reproducir las animaciones originales de baile o acciones del juego.

Aunque el visor funciona actualmente para la versión moderna de LoveBeat en Steam, próximamente añadiremos flags (parámetros de ejecución) para dar soporte y extraer correctamente los recursos de aquellas versiones clásicas y alternativas. Lograr esto no será una tarea sumamente compleja, ya que las distintas versiones comparten aproximadamente un 95% de similitud en la estructura de sus formatos, variando únicamente en pequeños detalles de encriptación o jerarquía.

🕵️‍♂️ Curiosidades Técnicas y Notas de Desarrollo

Durante el desarrollo de esta herramienta y la ingeniería inversa de los archivos del juego, nos topamos con decisiones de diseño fascinantes de aquella época:

• Un esqueleto para gobernarlos a todos: Resulta muy curioso descubrir que los avatares constan de un único esqueleto súper optimizado de apenas 30 huesos. Aún más sorprendente es que todos los personajes (niños, jóvenes e idols adultos) comparten exactamente este mismo esqueleto base, escalando las proporciones en tiempo de ejecución.
• Sistema de Ropa por Sustitución: A diferencia de sistemas modernos donde la ropa se dibuja "por encima" de un cuerpo base, para crear el inmenso catálogo de moda de LoveBeat optaron por reemplazar partes enteras del cuerpo. Cada prenda es un mesh (malla 3D) completo que sustituye totalmente al segmento anatómico (por ejemplo, al equipar una remera, se reemplaza el torso entero por uno nuevo que ya tiene la ropa esculpida). Esto les daba gran flexibilidad de diseño sin preocuparse por atravesar mallas (clipping).
• Rostros únicos: Uno pensaría que los rostros en juegos antiguos eran simplemente el mismo mesh de cabeza con una textura (dibujo) diferente pegada encima. ¡Pero no! En LoveBeat, cada expresión y cada rostro es un mesh completamente distinto e independiente. De hecho, casi cualquier cambio de textura viene acompañado de su propia malla 3D separada.

✨ Funcionalidades Principales

• Renderizado 3D Interactivo: El cliente web (construido con HTML, CSS y JavaScript mediante Three.js) dibuja los personajes del juego en 3D, permitiéndote rotarlos y hacer zoom libremente.
• Armado de Avatares (Mix & Match): Puedes equipar de forma individual distintas partes del cuerpo (cabeza, pelo, torso, pantalones, zapatos y accesorios) para crear tu propio avatar.
• Reproductor de Animaciones: Soporta la carga y reproducción en tiempo real de archivos de animación .ab.spak, aplicando los movimientos de baile reales del juego sobre el esqueleto del avatar.
• Explorador y Buscador: Cuenta con un catálogo visual donde puedes buscar y filtrar por nombre los miles de objetos disponibles dentro de los archivos del juego.
• Texturizado Automático: El visor detecta, desencripta y aplica dinámicamente las texturas .dds correspondientes a cada prenda de vestir.

⚠️ Limitaciones Actuales y Futuro

• Accesorios y Animaciones Adicionales: Por el momento, el sistema de animaciones para ciertos accesorios específicos (alas, mascotas, objetos en la mano) no está trabajado al 100%. Es posible que algunos de estos objetos no se animen correctamente o aparezcan desfasados de su posición original.
• Solo Avatares (Por Ahora): Hasta el momento, el esfuerzo se ha concentrado exclusivamente en decodificar y ensamblar a los personajes (avatares). En un futuro, se espera trabajar en la decodificación y reconstrucción de los escenarios (Game3D) del juego para poder renderizarlos completos en el visor.

⚠️ Importante: Este proyecto NO distribuye ni incluye los archivos originales del juego. Para que la herramienta funcione, cada usuario debe poseer su propia instalación legítima del juego de donde extraer los recursos.

🛠️ Requisitos de Instalación

Para correr este proyecto necesitas:

• Python 3.10 o superior instalado en tu sistema.
• Dependencias de Python (ubicadas en requirements.txt). Puedes instalarlas corriendo:

pip install -r requirements.txt

(Actualmente utilizamos Pillow para la conversión automática de texturas al vuelo).

🚀 Cómo usarlo

Para iniciar el WebViewer, ejecuta el siguiente comando en esta carpeta:

python serve.py

Esto iniciará el puente local en el puerto 18080 (o el siguiente que esté libre) y abrirá automáticamente tu navegador web con la interfaz del visor lista para usar.

¿Tienes el juego en otra carpeta?

Por defecto, la herramienta asume que está instalada dentro de la estructura estándar (LoveBeat/LoveBeat_Tools/WebViewer). Si tienes los archivos originales del juego en otra ruta, puedes iniciar el visor indicándole el directorio exacto:

python serve.py --game-dir "C:\Ruta\Hacia\Tu\LoveBeat"

📂 ¿Cómo está construido?

El WebViewer se compone de dos grandes partes:

1. El Cliente Frontend (JS/HTML/CSS): Es la interfaz visual que interactúa con el usuario. Administra la escena 3D, carga los recursos binarios enviados por el servidor, ensambla los esqueletos (huesos y vértices) y aplica interpolación para que las animaciones se vean fluidas. Toda esta lógica compleja vive del lado del navegador.

2. El Puente Local (Python): Un servidor liviano (lanzado al correr serve.py) que actúa como intermediario. Su única función es recibir los pedidos del visor web (ej. "dame la malla del pantalón X") y utilizar silenciosamente las herramientas del backend (Extractors/) para desencriptar, parsear a JSON y enviar los datos crudos del juego al navegador en cuestión de milisegundos.