StormJS
StormJS is StormLib for Javascript, powered by Emscripten.
StormLib is copyright © Ladislav Zezula. It is
licensed under the MIT license.
See src/vendor/StormLib/LICENSE
for more information.
Usage
To install StormJS:
npm install @ldcv/stormjs
To use StormJS in an ES2015 module environment:
import { FS, MPQ } from '@ldcv/stormjs';
// Mount the local filesystem path /home/stormjs/example as /stormjs
// This approach is suitable for cases where StormJS is running under Node
FS.mkdir('/stormjs');
FS.mount(FS.filesystems.NODEFS, { root: '/home/stormjs/example' }, '/stormjs');
const mpq = await MPQ.open('/stormjs/example.mpq', 'r');
const file = mpq.openFile('example.txt');
const data = file.read();
// Clean up
file.close();
mpq.close();
To use StormJS in browser:
const { MPQ } = require('@ldcv/stormjs');
// Fetch MPQ file from the server
const mpqBuffer = await fetch("path/to/your.mpq").then(res => res.arrayBuffer());
// Read uploaded MPQ file from file input
const fileReader = new FileReader();
const mpqBufferInput = await new Promise(resolve => {
fileReader.onload = evt => resolve(evt.target.result);
fileReader.readAsArrayBuffer( document.querySelector("input[type='file']").files[0] );
});
const mpq = await MPQ.fromArrayBuffer(mpqBuffer);
const file = mpq.openFile('example.txt');
const data = file.read();
// Clean up
file.close();
mpq.close();
Then pack the script using a packaging tool, such as Browserify:
browserify -o bundle.js your-script.js
Note that StormJS loads in production mode if process.env.NODE_ENV
is set to production
. In all other cases, StormJS loads in debug mode.
For production mode in browsers, you may exclude the debug library --exclude node_modules/@ldcv/stormjs/dist/stormlib.debug.js
from the packaging tool to reduce bundled script size.
API Reference
Please refer to API.md.
Compatibility
StormJS is tested against Node 10, 12, and 14; also tested in Chrome 92.
Additionally, StormJS should work well in other browsers with support for WASM. Note that use in browsers will require configuring an Emscripten filesystem type appropriate for the browser.
Development
Development of StormJS requires git, CMake, and an Emscripten environment.
emsdk is the simplest way to get an Emscripten environment up and running.
StormJS is currently built using Emscripten 1.39.15.
After cloning the StormJS repo, ensure all submodules are also pulled down from remote by running:
git submodule update --init --recursive
To build StormJS after making changes locally, run:
npm run build
The test suites for StormJS can be run using:
npm run test