README
gamecomp.js
Copyright 2018-2021 Adam Nielsen <malvineous@shikadi.net>
This is a Javascript library that can pass data through different algorithms used by MS-DOS games from the 1990s. Typically this is used to compress and decompress game data, as well as encrypt and decrypt it too.
Installation as an end-user
If you wish to use the command-line gamecomp
utility to work with the
algorithms directly, you can install the library globally on your system:
npm install -g @malvineous/gamecomp
Command line interface
The gamecomp
utility can be used to apply and reverse algorithms on data.
Data to process is supplied on stdin
and the processed data is sent to
stdout
. Use the --help
option to get a list of all the available options.
Some quick examples:
# List supported algorithms and their options
gamecomp --formats
# Compress a file using LZW with some custom options
gamecomp +cmp-lzw cwEOF=256 cwFirst=257 < clear.txt > out.lzw
# Decrypt a file with an XOR cipher using the default options
gamecomp -enc-xor-blood < crypt.bin > clear.bin
When specifying the algorithm in the first parameter, it is prefixed with a +
to apply the algorithm (compress/encrypt) or a -
to reverse it
(decompress/decrypt).
Installation as a dependency
If you wish to make use of the library in your own project, install it in the usual way:
npm install @malvineous/gamecomp
See cli/index.js
for example use. The quick start is:
const GameCompression = require('@malvineous/gamecomp');
// Decompress a file
const cmpAlgo = GameCompression.getHandler('cmp-lzw');
const input = fs.readFileSync('data.lzw');
const output = cmpAlgo.reveal(content);
fs.writeFileSync('data.raw', output);
// Encrypt the file with custom options
const crypto = GameCompression.getHandler('enc-xor-blood');
const output = crypto.obscure(input, {
seed: 123,
});
fs.writeFileSync('data.xor', output);
Installation as a contributor
If you would like to help add more file formats to the library, great! Clone the repo, and to get started:
npm install --dev
Run the tests to make sure everything worked:
npm run -s test
You're ready to go! To add a new algorithm:
Create a new file in the relevant subfolder for the algorithm type, such as
compress/
orencrypt/
.Edit the main
index.js
and add arequire()
statement for your new file.Make a folder in
test/
for your new algorithm and populate it with files similar to the others. The tests work by passing standard data to each algorithm and comparing the result to what is inside this folder. Run the tests just for your new algorithm (instead of all of them) by passing the grep (-g
) parameter to Mocha, the test framework. This will run any test matching the given string:npm run -s test -- -g cmp-myformat
Your tests will fail until you have created the expected sample files in the
tests/cmp-myformat/
folder.You can either create these files by hand, with another utility, or if you are confident that your code is correct, from the code itself. This is done by setting an environment variable when running the tests, which will cause the data produced by your code to be saved to a temporary file in the current directory:
SAVE_FAILED_TEST=1 npm run -s test -- -g cmp-myformat mv error1.bin test/cmp-myformat/default.bin
During development you can examine the output of your algorithm like this:
# Decompress (remove algo/reveal data)
$ DEBUG='gamecomp:cmp-myformat*' ./bin/gamecomp -cmp-myformat param=value < compressed.bin > clear.test
# Compress (apply algo/obscure data)
$ DEBUG='gamecomp:cmp-myformat*' ./bin/gamecomp +cmp-myformat param=value < clear.bin > compressed.test
If you use debug()
rather than console.log
then these messages can be left
in for future diagnosis as they will only appear when the DEBUG
environment
variable is set appropriately.