Skip to content

README.md

Latest commit

 

History

History
75 lines (53 loc) · 4.96 KB

README.md

File metadata and controls

75 lines (53 loc) · 4.96 KB
Raw

LoveBeat Tools - Extractores

Una colección de utilidades en Python diseñadas para extraer, analizar y convertir varios formatos propietarios utilizados por el motor del juego LoveBeat.

Estos scripts proveen todas las herramientas necesarias para extraer la totalidad de los recursos del juego, permitiendo analizar su estructura y llevar los archivos a formatos estándar (OBJ, DDS, OGG, SLK, XML, etc) para su modificación, preservación o renderizado externo (como el WebViewer).

Warning

Aviso de Compatibilidad: No se garantiza que estos extractores funcionen para todas las versiones anteriores o posteriores del cliente del juego. El desarrollo es continuo y se estará trabajando progresivamente para brindar un soporte integral a la compatibilidad histórica.

Requisitos

  • Python 3.8+
  • Bibliotecas estándar únicamente (no requiere dependencias externas)

Referencia de Herramientas

1. Desempaquetado y Desencriptación

extract_spak.py

Extrae archivos desde los contenedores .spak (QPACK).

  • Uso: python extract_spak.py <input_directory> [output_directory] [--workers N] [--overwrite]
  • Descripción: Lee la tabla de archivos codificada, descomprime los flujos de Zlib y extrae los archivos internos al disco. Soporta multithreading para extracción masiva.

extract_dds.py

Procesa los archivos de texturas .dds y .dds.spak.

  • Uso: python extract_dds.py <input> [output_dir] [--keystream path] [--allow-non-dds-output]
  • Descripción: Detecta automáticamente la versión del contenedor (v1 o v3), remueve las cabeceras QPACK si están empaquetados, y extrae texturas DDS estándar legibles.

extract_slk.py

Procesa las hojas de cálculo y configuración del juego (archivos .slk).

  • Uso: python extract_slk.py <love_exe_path> <encrypted_slk>... <output_dir> [--unescape-unicode] [--workers N]
  • Descripción: Requiere el ejecutable del juego (LoveBeat.exe) para poder procesar y exportar correctamente el contenido de las tablas originales.
  • Nota: Puede utilizar la flag --unescape-unicode para convertir de forma limpia las secuencias literales \uXXXX en caracteres nativos reales (útil para revisar las localizaciones asiáticas).

2. Modelos 3D y Esqueletos

export_skinned_part.py

Convierte las mallas de los personajes (ropa, pelo, cuerpo) desde los archivos mesh_*.gb o mesh_*.gb.spak a formatos estándar.

  • Uso: python export_skinned_part.py <input_file> [output_dir]
  • Descripción: Extrae vértices, coordenadas UV, índices y los pesos de los huesos (skinning weights). Exporta los datos en formato JSON/OBJ listos para motores 3D externos (como Three.js).

extract_gb.py

Convierte archivos .gb estáticos empaquetados directamente a modelos .obj.

  • Uso: python extract_gb.py <input_file>
  • Descripción: Un extractor rápido y directo para geometrías que no requieren datos de articulación (skinning).

extract_skeleton.py / extract_skeleton_runtime.py

Procesa y parsea archivos de jerarquía de esqueleto (por ejemplo, skel_boy.gb).

  • Descripción: Extrae las relaciones de huesos padre-hijo, las transformaciones locales y la matriz de la pose base (bind pose) necesaria para la animación de los personajes.

extract_item_bones.py

Extrae huesos adicionales desde los archivos bone_*.gb.spak.

  • Uso: python extract_item_bones.py <paths...> [--out OUT]
  • Descripción: Utilizado para parsear los huesos de animación secundaria anexados a los accesorios y ropa (ej. faldas, colas, pelo largo).

3. Audio y Animación

extract_ab_animations.py

Parsea los archivos de secuencia de animación (.ab).

  • Uso: python extract_ab_animations.py <input_file>
  • Descripción: Extrae los fotogramas clave (keyframes) y los datos de interpolación (rotación/traslación) por cada hueso. Exporta el resultado en formato JSON para su reproducción externa.

extract_snb_ogg.py

Reconstruye el audio a partir de los archivos de música de fondo (.snb).

  • Uso: python extract_snb_ogg.py <input> <output> [--donors DIR_1 DIR_2]
  • Descripción: El juego elimina la cabecera estándar de los archivos OGG por razones de seguridad. Este script une los paquetes de configuración y los codebooks faltantes provenientes de archivos OGG "donantes" con el flujo de bits bruto del SNB, para recrear un archivo .ogg perfectamente reproducible.
  • Advertencia: La extracción de archivos .snb es un proceso de prueba y error. No se garantiza obtener un audio legible al primer intento para todos los archivos. Es necesario probar poco a poco proporcionando diferentes carpetas de archivos .ogg donantes hasta encontrar cabeceras compatibles para los audios que falten reconstruir.

WebViewer

Varios de estos extractores están diseñados y son utilizados directamente en conjunto con el servidor del WebViewer incluido en este repositorio para renderizar y visualizar los recursos del juego en el navegador.