@araxiaonline/mpq-tools-osx/README.md

Node.js wrapper for MPQ archive manipulation for MacOSX using mpqcli

# mpq-tools-osx

A Node.js wrapper for manipulating MPQ archives using mpqcli. This package provides a simple interface to list, extract, and create MPQ archives commonly used in Blizzard games.

## Prerequisites

- Node.js >= 14.0.0
- CMake (for building mpqcli)
- C++ compiler (for building mpqcli)

## Installation

```bash
npm install mpq-tools-osx
```

The package will automatically build mpqcli during installation.

## Usage

```javascript
const MPQTool = require('mpq-tools');
const mpq = new MPQTool();

// List all files in an MPQ archive
const files = mpq.listFiles('path/to/archive.mpq');
console.log(`Found ${files.length} files`);

// Search for specific files
const swordSounds = mpq.searchFiles('path/to/archive.mpq', 'Sword');
console.log(`Found ${swordSounds.length} sword sound files`);

// Extract a specific file
mpq.extractFile('path/to/archive.mpq', 'path/inside/archive.txt', 'output/dir');

// Extract all files
mpq.extractAll('path/to/archive.mpq', 'output/dir');

// Create a new MPQ archive from a directory
mpq.createArchive('directory/to/archive', 2); // version 2 MPQ
```

## API

### `new MPQTool(options)`

Create a new MPQTool instance.

Options:

- `mpqcliPath`: Optional path to the mpqcli executable. By default, it uses the bundled version.

### `listFiles(mpqFile)`

List all files in an MPQ archive.

- `mpqFile`: Path to the MPQ file
- Returns: Array of file paths in the archive

### `searchFiles(mpqFile, pattern)`

Search for files in an MPQ archive using a pattern.

- `mpqFile`: Path to the MPQ file
- `pattern`: Search pattern (case-insensitive)
- Returns: Array of matching file paths

### `extractFile(mpqFile, filePath, outputDir)`

Extract a specific file from an MPQ archive.

- `mpqFile`: Path to the MPQ file
- `filePath`: Path of the file within the archive to extract
- `outputDir`: Optional output directory
- Returns: true if successful

### `extractAll(mpqFile, outputDir)`

Extract all files from an MPQ archive.

- `mpqFile`: Path to the MPQ file
- `outputDir`: Optional output directory
- Returns: true if successful

### `createArchive(directory, version, outputPath, options)`

Create a new MPQ archive from a directory.

- `directory`: Directory to create MPQ from
- `version`: MPQ version (1 or 2, default: 2)
- `outputPath`: Optional path for the MPQ file. If not provided, creates it next to the directory
- `options`: Additional options object:
  - `addFiles`: If true, automatically adds all files from the directory to the archive (default: false)
- Returns: Path to the created MPQ file

Example:
```javascript
// Create MPQ and automatically add all files from the directory
const mpqPath = mpq.createArchive('directory/to/archive', 2, 'output.mpq', { addFiles: true });
console.log(`Created and populated MPQ at: ${mpqPath}`);

// Create empty MPQ (traditional way)
const emptyMpqPath = mpq.createArchive('directory/to/archive', 2);
```

### Example command line command

```bash
node -e "const MPQTool = require('./lib'); const mpq = new MPQTool(); mpq.addFile('patch-C.MPQ', 'test.txt', 'custom/test.txt');"
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.