bg2-io es una biblioteca que unifica todas las APIs de lectura y escritura del formato de assets de bg2 engine.
En la versión 1.x de bg2 engine, las APIs de C++ y de JavaScript implementaban sus funciones de lectura y escritura de assets, lo que dificultaba bastante el mantenimiento porque el código residía en diferentes repositorios. Además, el código estaba duplicado en ambos lenguajes de programación diferentes.
Este proyecto surge como solución a este problema.
Descripción
bg2-io unifica en un mismo repositorio bibliotecas de lectura y escritura del formato de archivo bg2 con una serie de utilidades de conversión de formato del archivo.
En la biblioteca hay definidas tres APIs diferentes:
- bg2-io: escritura y lectura de ficheros bg2, en lenguaje C
- bg2-io-net: lectura de ficheros bg2, en lenguaje C#. Aquí no se ha implementado la escritura, porque su caso de uso es posibilitar la carga de assets de bg2 engine en otros motores implementados en C#, como pueden ser Unity o Godot
- wasm: escritura y lectura de ficheros bg2, mediante WebAssembly generado a partir de bg2-io utilizando Emscripten. En esta parte también se implementa un wrapper en JavaScript para facilitar el uso del API.
Además de las bibliotecas, en el directorio de código fuente también hay varios ejemplos de uso y algunas utilidades, entre las que destacan:
- bg2json: genera archivos JSON con la información de un fichero de asset bg2
- bg2obj: exporta un asset bg2 a formato Wavefront OBJ.
- gltf-export: exporta un asset bg2 a formato GLTF. Esta utilidad se encuentra también precompilada en el directorio
bindentro del repositorio, para Linux y Windows de 64 bits y para macOS en formato universal Intel y Apple Silicon.
Destacado
Este proyecto es un ejemplo del uso de Emscripten para generar WebAssembly a partir de código fuente en lenguaje C. En el directorio src/wasm tenemos a su vez dos sub directorios c y js que implementan el wrapper. En el fichero c/wrapper.c tenemos un ejemplo de cómo implementar funciones que podemos invocar desde JavaScript. En la otra parte, el fichero js/Bg2ioWrapper.mjs muestra cómo se realiza la invocación de las funciones del wrapper, y lo más interesante, cómo se realiza la adquisición de los datos del heap de WebAssembly para devolverlos en formato de objetos JavaScript.
De la parte del API de C cabe destacar la forma en que está implementada, leyendo y escribiendo buffers en memoria en lugar de utilizar el sistema de ficheros. La implementación se hizo de esta forma sabiendo que el API iba a ser convertida a formato WebAssembly, y que en este caso sería mucho más sencillo implementar un wrapper usando buffers de memoria. Esta implementación nos da flexibilidad suficiente para leer y escribir los datos del fichero. Por ejemplo, podemos usar el paquete node:fs en una aplicación de servidor en el backend, o bien utilizar fetch en una aplicación de cliente en el frontend. En ambos casos trabajaremos con un buffer, ya sea de entrada o de salida.
Disponibilidad
El proyecto está publicado con licencia MIT y se puede obtener a través de su repositorio de Github o del paquete en NPM:
https://github.com/ferserc1/bg2-io
https://www.npmjs.com/package/bg2io