### Programmatic Usage Example

Source: https://github.com/chiefofgxbxl/wc3maptranslator/blob/master/README.md

Demonstrates how to import and use individual translators from the wc3maptranslator library to convert JSON data into WarCraft III's binary format. This example shows the translation of camera data.

```APIDOC
## Programmatic Usage

```ts
import {
  CamerasTranslator,
  DoodadsTranslator,
  ImportsTranslator,
  InfoTranslator,
  ObjectsTranslator,
  RegionsTranslator,
  SoundsTranslator,
  StringsTranslator,
  TerrainTranslator,
  UnitsTranslator
} from 'wc3maptranslator';

// E.g. let's create a camera for the map
const cameras = [
  {
    "target": {
      "x": -319.01,
      "y": -90.18
    },
    "offsetZ": 0,
    "rotation": 90,
    "aoa": 304,
    "distance": 2657.34,
    "roll": 5,
    "fov": 70,
    "farClipping": 5000,
    "name": "MyCamera1"
  }
]

// Now translate the JSON into the WarCraft III format
// All translators have: `.jsonToWar` and `.warToJson` functions
const translatedResult = CamerasTranslator.jsonToWar(cameras);

// `translatedResult` contains a `buffer` which can be saved to disk
// This war3map.w3c file can now be placed inside a .w3x via an MPQ
// editor, and you should now see a camera in the Camera Palette!
// fs.writeFileSync('war3map.w3c', translatedResult.buffer);
```

### Translators Available

- **CamerasTranslator**: For `war3map.w3c` files.
- **DoodadsTranslator**: For `war3map.doo` files.
- **ImportsTranslator**: For import files.
- **InfoTranslator**: For `war3map.w3i` files.
- **ObjectsTranslator**: For custom object data.
- **RegionsTranslator**: For `war3map.w3r` files.
- **SoundsTranslator**: For sound data.
- **StringsTranslator**: For string data.
- **TerrainTranslator**: For `war3map.w3e` files.
- **UnitsTranslator**: For `war3mapUnits.doo` files.

Each translator provides `jsonToWar(jsonData)` and `warToJson(buffer)` methods.
```

--------------------------------

### Example Import Data Array

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Imports

An example of the expected format for the importData array, showing both standard and custom import types.

```javascript
[
    { path: "file1.mdx", type: 'standard' },
    { path: "file2.blp", type: 'custom' },
]
```

--------------------------------

### Install WC3MapTranslator Globally

Source: https://github.com/chiefofgxbxl/wc3maptranslator/blob/master/README.md

Install the package globally for command-line interface usage. For local project installation, omit the -g flag. Requires Node.js version 24 or higher.

```sh
npm install -g wc3maptranslator
```

--------------------------------

### Install WC3MapTranslator

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Install WC3MapTranslator globally for CLI usage or locally as a Node.js module.

```sh
# Global install (recommended for CLI usage)
npm install -g wc3maptranslator
```

```sh
# Local install (for programmatic use)
npm install wc3maptranslator
```

--------------------------------

### CLI Usage Examples

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Demonstrates various command-line operations for translating WarCraft III map files and directories. Auto-detection of translation direction is supported, or can be forced with flags.

```sh
# Auto-detect: JSON -> war3map binary (filename matches known JSON name)
wc3maptranslator terrain.json
# Output: war3map.w3e in the current directory
```

```sh
# Auto-detect: war3map binary -> JSON
wc3maptranslator war3map.w3i
# Output: info.json in the current directory
```

```sh
# Specify custom output path
wc3maptranslator war3map.w3c ./output/cameras.json
```

```sh
# Translate an entire directory of war3map binary files to JSON
wc3maptranslator ./MyMap.w3x --toJson
```

```sh
# Translate an entire directory of JSON files back to war3map binaries
wc3maptranslator ./my-map-json/ --toWar ./output-dir/
```

```sh
# Force overwrite existing output files
wc3maptranslator war3map.w3e --force
```

```sh
# Silent mode (suppress success messages, errors still shown)
wc3maptranslator war3map.w3s --silent
```

```sh
# List all supported translators and their standard file names
wc3maptranslator --list
```

```sh
# Show help
wc3maptranslator --help
```

--------------------------------

### Programmatic Usage: Import and Use Translators

Source: https://github.com/chiefofgxbxl/wc3maptranslator/blob/master/README.md

Import specific translators from the 'wc3maptranslator' module. This example demonstrates creating a camera object and translating it from JSON to the WarCraft III format using the CamerasTranslator.

```ts
import {
  CamerasTranslator,
  DoodadsTranslator,
  ImportsTranslator,
  InfoTranslator,
  ObjectsTranslator,
  RegionsTranslator,
  SoundsTranslator,
  StringsTranslator,
  TerrainTranslator,
  UnitsTranslator
} from 'wc3maptranslator';

// E.g. let's create a camera for the map
const cameras = [
  {
    "target": {
      "x": -319.01,
      "y": -90.18
    },
    "offsetZ": 0,
    "rotation": 90,
    "aoa": 304,
    "distance": 2657.34,
    "roll": 5,
    "fov": 70,
    "farClipping": 5000,
    "name": "MyCamera1"
  }
]

// Now translate the JSON into the WarCraft III format
// All translators have: `.jsonToWar` and `.warToJson` functions
const translatedResult = CamerasTranslator.jsonToWar(cameras);

// `translatedResult` contains a `buffer` which can be saved to disk
// This war3c file can now be placed inside a .w3x via an MPQ
// editor, and you should now see a camera in the Camera Palette!
fs.writeFileSync('war3map.w3c', translatedResult.buffer);
```

--------------------------------

### Modify Footman and Create Custom Unit (JSON)

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Objects

Example demonstrating how to modify an existing unit (human footman) and create a new custom unit based on it, specifying fields like movement speed, mana regeneration, and attack damage.

```json
{
    "original": {
        "hfoo": [
            { "id": "umvs", "value": 500 },
            { "id": "umpr", "type": "unreal", "value": 452.14 },
            { "id": "ua1b", "type": "int", "value": 77 }
        ]
    },
    "custom": {
        "h000:hfoo": [
            { "id": "ua1b", "type": "int", "value": 13 },
            { "id": "uhpm", "value": 999 },
            { "id": "utip", "value": "hey there! this is a custom footman, woohoo~" }
        ]
    }
}
```

--------------------------------

### Modify Buff and Create Custom Spell (JSON)

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Objects

Example for modifying an existing buff (avatar) and creating a new custom spell (banish), specifying fields like faction and effect.

```json
{
    "original": {
        "BHav": [
            { "id": "fnam", "value": "hello world!" }
        ]
    },
    "custom": {
        "B000:BHbn": [
            { "id": "frac", "value": "orc" },
            { "id": "feff", "value": 1 }
        ]
    }
}
```

--------------------------------

### Modify Holy Light Ability (JSON)

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Objects

Example showing how to modify the healing values and icon for the Holy Light ability. Note the use of 'column' and 'level' for ability-specific fields.

```json
{
    "original": {
        "AHhb": [
            { "id": "Hhb1", "column": 1, "level": 1, "value": 1200, "type": "unreal" },
            { "id": "Hhb1", "column": 1, "level": 2, "value": 2400, "type": "unreal" },
            { "id": "Hhb1", "column": 1, "level": 3, "value": 3600, "type": "unreal" },
            
            { "id": "aart", "value": "ReplaceableTextures\CommandButtons\BTNHowlOfTerror.blp" }
        ]
    },
    "custom": {}
}
```

--------------------------------

### Translate war3map.w3i to JSON and back

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Use InfoTranslator to convert a `war3map.w3i` file to a JSON object and vice-versa. Enums are exposed as static properties for easier use. Ensure the `fs-extra` library is installed for file operations.

```typescript
import { InfoTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

const { PlayerType, PlayerRace, FogType, ScriptLanguage, SupportedModes, GameDataVersion, GameDataSet, UpgradeAvailability } = InfoTranslator;

const info = {
  saves: 0,
  editorVersion: 6072,
  gameVersion: { major: 1, minor: 32, patch: 10, build: 20268 },
  gameDataSet: GameDataSet.Default,
  gameDataVersion: GameDataVersion.TFT,
  scriptLanguage: ScriptLanguage.Lua,
  supportedModes: SupportedModes.Both,
  map: {
    name: 'My Custom Map',
    author: 'Mapmaker',
    description: 'A 2v2 skirmish map.',
    recommendedPlayers: '2v2',
    playableArea: { width: 96, height: 96 },
    mainTileType: 'L',
    flags: {
      hideMinimapInPreview: false,
      modifyAllyPriorities: true,
      isMeleeMap: false,
      maskedPartiallyVisible: false,
      fixedPlayerSetting: true,
      useCustomForces: true,
      useCustomTechtree: false,
      useCustomAbilities: false,
      useCustomUpgrades: false,
      waterWavesOnCliffShores: true,
      waterWavesOnRollingShores: false,
      useTerrainFog: true,
      useItemClassificationSystem: true,
      enableWaterTinting: false,
      useAccurateProbabilityForCalculations: false,
      useCustomAbilitySkins: false,
      disableDenyIcon: false,
      forceDefaultCameraZoom: false,
      forceMaxCameraZoom: false,
      forceMinCameraZoom: false
    }
  },
  camera: {
    bounds: [-3328, -3328, 3328, 3328, -3328, 3328, 3328, -3328],
    complements: [512, 512, 512, 512]
  },
  prologue: { path: '', text: '', title: '', subtitle: '' },
  loadingScreen: { background: -1, path: '', text: 'Loading...', title: 'My Map', subtitle: '' },
  fog: { type: FogType.Linear, startHeight: 1000, endHeight: 5000, density: 0.5, color: [128, 128, 200] },
  globalWeather: 'none',
  customSoundEnvironment: '',
  customLightEnv: 'L',
  water: [0, 128, 255],
  forceDefaultCameraZoom: 0,
  forceMaxCameraZoom: 0,
  forceMinCameraZoom: 0,
  players: [
    {
      playerNum: 0,
      type: PlayerType.Human,
      race: PlayerRace.Human,
      name: 'Player 1',
      startingPos: { x: -1024, y: -1024, fixed: true }
    },
    {
      playerNum: 1,
      type: PlayerType.Human,
      race: PlayerRace.Orc,
      name: 'Player 2',
      startingPos: { x: 1024, y: 1024, fixed: true }
    }
  ],
  forces: [
    {
      name: 'Players',
      flags: { allied: true, alliedVictory: true, shareVision: true, shareUnitControl: false, shareAdvUnitControl: false },
      players: [0, 1]
    }
  ],
  upgrades: [
    { players: [0], id: 'Rhme', level: 0, availability: UpgradeAvailability.Researched }
  ],
  techtree: [],
  randomGroupTable: [],
  randomItemTable: []
};

const warResult = InfoTranslator.jsonToWar(info);
fs.writeFileSync('war3map.w3i', warResult.buffer);

// war3map binary -> JSON
const buffer = fs.readFileSync('war3map.w3i');
const { json } = InfoTranslator.warToJson(buffer);
console.log(json.map.name);       // 'My Custom Map'
console.log(json.players.length); // 2
console.log(json.fog.type);       // 0 (FogType.Linear)
```

--------------------------------

### Player Object Specification

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Info

Defines the structure for a Player object within the infoData. Includes type, race, player number, name, and starting position.

```json
{
    type: <Int>,
    race: <Int>,
    playerNum: <Int>,
    name: <String>,
    startingPos: { x: <Float>, y: <Float> }
}
```

--------------------------------

### CLI Usage: List Translators and Help

Source: https://github.com/chiefofgxbxl/wc3maptranslator/blob/master/README.md

View a list of all available translators and their standard file names using the --list flag. Access comprehensive usage instructions with the --help flag.

```sh
# See list of available translators and standard file names
wc3maptranslator --list

# See help
wc3maptranslator --help
```

--------------------------------

### Convert JSON to Warcraft 3 Region File

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Regions

Use this method to convert a JSON array of region data into the binary format for a .w3r file. The output buffer can then be written directly to a file.

```javascript
import { RegionsTranslator } from 'wc3maptranslator';
var result = RegionsTranslator.jsonToWar(regionData);
// Now you can write result.buffer to a war3map.w3r file
```

--------------------------------

### Translate Warcraft 3 Binary Object Data to JSON

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Use this to convert Warcraft 3 binary files back into JSON format for abilities or destructables. For destructables, both the main and skin binary files are required.

```typescript
// war3map binary -> JSON (abilities)
const buffer = fs.readFileSync('war3map.w3a');
const { json } = ObjectsTranslator.warToJson(ObjectType.Abilities, buffer);
console.log(Object.keys(json.original)); // original ability IDs
console.log(Object.keys(json.custom));   // custom ability IDs like 'A000:AHbz'
```

```typescript
// war3map binary -> JSON (destructables with skin file)
const w3bBuffer = fs.readFileSync('war3map.w3b');
const skinBuffer = fs.readFileSync('war3mapSkin.w3b');
const { json: destJson } = ObjectsTranslator.warToJson(ObjectType.Destructables, w3bBuffer, skinBuffer);
// Both buffers are merged into one unified json result
```

--------------------------------

### Translate JSON to Warcraft 3 Binary Object Data

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Use this to convert JSON data into Warcraft 3 binary files for units or destructables. Destructables require special handling as they can output two files.

```typescript
import { ObjectsTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

const { ObjectType } = ObjectsTranslator;

// Modify original units and add a custom unit
const unitsTable = {
  original: {
    'hfoo': [  // modify base Footman
      { id: 'unam', type: 'string', value: 'Elite Footman' },
      { id: 'uhpm', type: 'int',    value: 600 }  // hp max
    ]
  },
  custom: {
    'h001:hfoo': [  // h001 is the custom ID, hfoo is the base
      { id: 'unam', type: 'string', value: 'Captain' },
      { id: 'ua1m', type: 'int',    value: 5 }   // ability 1 max level
    ]
  }
};

// JSON -> war3map binary (units)
const warResult = ObjectsTranslator.jsonToWar(ObjectType.Units, unitsTable);
fs.writeFileSync('war3map.w3u', warResult.buffer);

// JSON -> war3map binary (destructables — outputs TWO buffers)
const destructablesTable = {
  original: {
    'LTlt': [
      { id: 'bnam', type: 'string', value: 'My Custom Tree' },
      { id: 'bsel', type: 'real',   value: 1.5 }
    ]
  },
  custom: {}
};
const destResult = ObjectsTranslator.jsonToWar(ObjectType.Destructables, destructablesTable);
fs.writeFileSync('war3map.w3b', destResult.buffer);
if (destResult.bufferSkin) {
  fs.writeFileSync('war3mapSkin.w3b', destResult.bufferSkin); // skin fields go here
}
```

--------------------------------

### Translate war3map.w3s Binary to Sounds JSON

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts the binary war3map.w3s file into a JSON array of sound definitions. The channel property in the resulting JSON will be a numeric code.

```typescript
import { SoundsTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

// war3map binary -> JSON
const buffer = fs.readFileSync('war3map.w3s');
const { json } = SoundsTranslator.warToJson(buffer);
console.log(json[0].variableName); 
console.log(json[0].channel); 
```

--------------------------------

### Convert JSON Sound Data to War3map.w3s Format

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Sounds

Use this snippet to convert a JSON array of sound objects into the binary format required for war3map.w3s files. Ensure 'soundData' is correctly structured according to the specification.

```javascript
import { SoundsTranslator } from 'wc3maptranslator';
var result = SoundsTranslator.jsonToWar(soundData);
// Now you can write result.buffer to a war3map.w3s file
```

--------------------------------

### CLI Usage: Translate Entire Folders

Source: https://github.com/chiefofgxbxl/wc3maptranslator/blob/master/README.md

Translate all map files within a specified directory. Use --toJson to convert WarCraft III formats to JSON, and --toWar to convert JSON files to WarCraft III formats.

```sh
# Usage (translate an entire folder)
wc3maptranslator ./path/to/war3mapFiles --toJson
wc3maptranslator ./path/to/jsonFiles --toWar
```

--------------------------------

### Warcraft III Trigger String Data Format

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/war3map.wts:-Trigger-String-Data

Illustrates the basic format for defining string constants within Warcraft III map files. Each string is identified by a unique ID and enclosed in curly braces.

```plaintext
STRING 1
{
Player 1
}

STRING 2
{
Force 1
}

(etc.)
```

--------------------------------

### WC3 Sound Data Structure Specification

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Sounds

Defines the structure for sound objects when converting to Warcraft III's sound format. Key properties include name, path, EAX settings, flags, fade rates, volume, pitch, channel, and distance properties.

```javascript
soundData: [<Sound>]; // Array of sounds
```

```javascript
{
    name: <String> // e.g. "gg_snd_HumanGlueScreenLoop1",
    path: <String> // e.g. "Sound\Ambient\HumanGlueScreenLoop1.wav",
    eax: <String = "DefaultEAXON">
    flags: {
        looping: <Boolean = false>,
        3dSound: <Boolean = false>,
        stopOutOfRange: <Boolean = false>,
        music: <Boolean = false>
    },
    fadeRate: { <Object = {in:10, out:10}>
        in: <Integer = 10>,
        out: <Integer = 10>
    },
    volume: <Integer = -1>,
    pitch: <Float = 1.0>,
    channel: <Integer = 0>,
    distance: {
        min: <Integer>,
        max: <Integer>,
        cutoff: <Integer>
    }
}
```

--------------------------------

### CamerasTranslator API

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

The CamerasTranslator allows conversion of WarCraft III camera data between JSON and the binary war3map.w3c format. It supports methods for both JSON to War (binary) and War (binary) to JSON translations.

```APIDOC
## CamerasTranslator

Translates the `war3map.w3c` file that defines cinematic/editor cameras in the Camera Palette; all angles are in degrees and distances in world units.

```ts
import { CamerasTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

// JSON -> war3map binary
const cameras = [
  {
    name: 'IntroCamera',
    target: { x: -319.01, y: -90.18 },
    offsetZ: 0,
    rotation: 90,       // degrees
    aoa: 304,           // angle of attack, degrees
    distance: 2657.34,
    roll: 0,
    fov: 70,            // field of view, degrees
    farClipping: 5000,
    nearClipping: 100,
    localPitch: 0,
    localYaw: 0,
    localRoll: 0
  }
];

const warResult = CamerasTranslator.jsonToWar(cameras);
fs.writeFileSync('war3map.w3c', warResult.buffer);

// war3map binary -> JSON
const buffer = fs.readFileSync('war3map.w3c');
const jsonResult = CamerasTranslator.warToJson(buffer);
console.log(jsonResult.json);
// [{ name: 'IntroCamera', target: { x: -319.01, y: -90.18 }, rotation: 90, ... }]
```

### Methods

- **`jsonToWar(data: Camera[]): WarResult`**: Converts a JSON array of camera objects to a WarCraft III binary buffer.
- **`warToJson(buffer: Buffer): JsonResult<Camera[]>`**: Converts a WarCraft III binary buffer of camera data to a JSON array of camera objects.
```

--------------------------------

### Translate war3map.w3r Binary to Regions JSON

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts the binary war3map.w3r file into a JSON array of region definitions. The color property in the resulting JSON will be in RGB order.

```typescript
import { RegionsTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

// war3map binary -> JSON
const buffer = fs.readFileSync('war3map.w3r');
const { json } = RegionsTranslator.warToJson(buffer);
console.log(json[0].name); 
console.log(json[0].color); 
```

--------------------------------

### CLI Usage: Translate Individual Files

Source: https://github.com/chiefofgxbxl/wc3maptranslator/blob/master/README.md

Translate single JSON or WarCraft III map files. The output file is created in the current working directory. If the output file already exists, the translation is skipped by default unless the --force flag is used.

```sh
# wc3maptranslator <input> [output]

# Usage (individual files, same directory)
wc3maptranslator terrain.json  # outputs war3map.w3e in CWD
wc3maptranslator war3map.w3i  # outputs info.json in CWD
```

--------------------------------

### Translate WC3 Map to JSON and vice-versa

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Home

Use `jsonToWar` to convert JSON data to WC3 map format, and `warToJson` to convert WC3 map data to JSON. The translators return an object containing potential errors and the converted data.

```javascript
import { RegionsTranslator } from 'wc3maptranslator';
var result = RegionsTranslator.jsonToWar(data); // for taking a JSON file and getting the WC3 data
var result2 = RegionsTranslator.warToJson(data2); // for taking WC3 data and getting the JSON representation
```

--------------------------------

### Translate war3map.imp Binary to Imports JSON

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts the binary war3map.imp file into a JSON array of imported file paths.

```typescript
import { ImportsTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

// war3map binary -> JSON
const buffer = fs.readFileSync('war3map.imp');
const { json } = ImportsTranslator.warToJson(buffer);
console.log(json);
// ['war3mapImported\hero_skin.blp', 'war3mapImported\custom_ui.tga', ...]
```

--------------------------------

### jsonToWar

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Sounds

Converts sound data from JSON format to the war3map.w3s file format.

```APIDOC
## jsonToWar

### Description
Converts an array of sound objects from JSON format into a buffer that can be written to a war3map.w3s file.

### Method
SoundsTranslator.jsonToWar(soundData)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **soundData** (Array<Sound>) - Required - An array of sound objects to be converted.

### Request Example
```json
[
  {
    "name": "gg_snd_HumanGlueScreenLoop1",
    "path": "Sound\\Ambient\\HumanGlueScreenLoop1.wav",
    "eax": "DefaultEAXON",
    "flags": {
      "looping": false,
      "3dSound": false,
      "stopOutOfRange": false,
      "music": false
    },
    "fadeRate": {
      "in": 10,
      "out": 10
    },
    "volume": -1,
    "pitch": 1.0,
    "channel": 0,
    "distance": {
      "min": 0,
      "max": 0,
      "cutoff": 0
    }
  }
]
```

### Response
#### Success Response (Buffer)
- **buffer**: A Buffer object containing the binary data for the war3map.w3s file.

#### Response Example
```javascript
// Assuming result is the output of jsonToWar
// result.buffer can be written to a war3map.w3s file
```

### Sound Structure Definition
```json
{
    name: <String>, // e.g. "gg_snd_HumanGlueScreenLoop1",
    path: <String>, // e.g. "Sound\\Ambient\\HumanGlueScreenLoop1.wav",
    eax: <String = "DefaultEAXON">, // Options: DefaultEAXON, CombatSoundsEAX, KotoDrumsEAX, SpellsEAX, MissilesEAX, HeroAcksEAX, DoodadsEAX
    flags: {
        looping: <Boolean = false>,
        3dSound: <Boolean = false>,
        stopOutOfRange: <Boolean = false>,
        music: <Boolean = false>
    },
    fadeRate: { <Object = {in:10, out:10}> 
        in: <Integer = 10>,
        out: <Integer = 10>
    },
    volume: <Integer = -1>,
    pitch: <Float = 1.0>,
    channel: <Integer = 0>, // Options: 0=General, 1=Unit Selection, 2=Unit Acknowledgment, 3=Unit Movement, 4=Unit Ready, 5=Combat, 6=Error, 7=Music, 8=User Interface, 9=Looping Movement, 10=Looping Ambient, 11=Animations, 12=Constructions, 13=Birth, 14=Fire
    distance: {
        min: <Integer>,
        max: <Integer>,
        cutoff: <Integer>
    }
}
```
```

--------------------------------

### CLI Usage: Force Overwrite and Silence Output

Source: https://github.com/chiefofgxbxl/wc3maptranslator/blob/master/README.md

Use the --force or -f flag to overwrite existing output files. Employ the --silent or -s flag to suppress success messages, though errors will still be displayed.

```sh
# Useful flags
--force / -f Overwrite existing files (by default, translation is skipped if it would overwrite an existing file)
--silent / -s Silence success output messages (errors will still be shown)
```

--------------------------------

### CamerasTranslator: War3map Binary to JSON

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts the binary `war3map.w3c` file into a JSON representation of camera data. The output is a `JsonResult` object containing the parsed JSON.

```ts
// war3map binary -> JSON
const buffer = fs.readFileSync('war3map.w3c');
const jsonResult = CamerasTranslator.warToJson(buffer);
console.log(jsonResult.json);
// [{ name: 'IntroCamera', target: { x: -319.01, y: -90.18 }, rotation: 90, ... ]
```

--------------------------------

### Translate Imports JSON to war3map.imp Binary

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts a JSON array of imported file paths to the binary war3map.imp format.

```typescript
import { ImportsTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

// JSON -> war3map binary
const imports = [
  'war3mapImported\hero_skin.blp',
  'war3mapImported\custom_ui.tga',
  'war3mapImported\loadingscreen.tga'
];

const warResult = ImportsTranslator.jsonToWar(imports);
fs.writeFileSync('war3map.imp', warResult.buffer);
```

--------------------------------

### Batch Convert Map Files to JSON

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts all known map files in a directory to JSON format. Ensure the input directory exists and contains the map files. The output directory will be created if it doesn't exist.

```typescript
import {
  CamerasTranslator, DoodadsTranslator, ImportsTranslator, InfoTranslator,
  ObjectsTranslator, RegionsTranslator, SoundsTranslator, StringsTranslator,
  TerrainTranslator, UnitsTranslator
} from 'wc3maptranslator';
import * as fs from 'fs-extra';
import path from 'path';

const { ObjectType } = ObjectsTranslator;

const mapDir = './MyMap.w3x-extracted';
const outDir = './my-map-json';
fs.ensureDirSync(outDir);

const conversions: Array<{ file: string; translator: (buf: Buffer) => { json: unknown } }> = [
  { file: 'war3map.w3e',	translator: (b) => TerrainTranslator.warToJson(b) },
  { file: 'war3mapUnits.doo',	translator: (b) => UnitsTranslator.warToJson(b) },
  { file: 'war3map.doo',	translator: (b) => DoodadsTranslator.warToJson(b) },
  { file: 'war3map.w3r',	translator: (b) => RegionsTranslator.warToJson(b) },
  { file: 'war3map.w3c',	translator: (b) => CamerasTranslator.warToJson(b) },
  { file: 'war3map.w3s',	translator: (b) => SoundsTranslator.warToJson(b) },
  { file: 'war3map.wts',	translator: (b) => StringsTranslator.warToJson(b) },
  { file: 'war3map.imp',	translator: (b) => ImportsTranslator.warToJson(b) },
  { file: 'war3map.w3i',	translator: (b) => InfoTranslator.warToJson(b) },
  { file: 'war3map.w3u',	translator: (b) => ObjectsTranslator.warToJson(ObjectType.Units, b) },
  { file: 'war3map.w3t',	translator: (b) => ObjectsTranslator.warToJson(ObjectType.Items, b) },
  { file: 'war3map.w3a',	translator: (b) => ObjectsTranslator.warToJson(ObjectType.Abilities, b) },
  { file: 'war3map.w3q',	translator: (b) => ObjectsTranslator.warToJson(ObjectType.Upgrades, b) },
  { file: 'war3map.w3h',	translator: (b) => ObjectsTranslator.warToJson(ObjectType.Buffs, b) },
];

for (const { file, translator } of conversions) {
  const inputPath = path.join(mapDir, file);
  if (!fs.existsSync(inputPath)) continue;

  try {
    const buffer = fs.readFileSync(inputPath);
    const { json } = translator(buffer);
    const outputFile = path.join(outDir, file.replace(/\.\w+$/, '.json'));
    fs.writeFileSync(outputFile, JSON.stringify(json, null, 2));
    console.log(`Converted ${file} -> ${path.basename(outputFile)}`);
  } catch (e) {
    console.error(`Failed to convert ${file}:`, (e as Error).message);
  }
}
```

--------------------------------

### Translate war3map Units Binary to JSON

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts the binary war3mapUnits.doo file back into a JSON representation of units and items. The resulting JSON object contains detailed properties for each unit, including hero stats and inventory.

```typescript
// war3map binary -> JSON
const buffer = fs.readFileSync('war3mapUnits.doo');
const jsonResult = UnitsTranslator.warToJson(buffer);
console.log(jsonResult.json[0].type);
console.log(jsonResult.json[2].hero);
```

--------------------------------

### ImportsTranslator

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Translates the `war3map.imp` imported files manifest. The JSON representation is a plain string array of file paths.

```APIDOC
## ImportsTranslator

Translates the `war3map.imp` imported files manifest; the JSON is a plain string array of file paths.

```ts
import { ImportsTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

// JSON -> war3map binary
const imports = [
  'war3mapImported\hero_skin.blp',
  'war3mapImported\custom_ui.tga',
  'war3mapImported\loadingscreen.tga'
];

const warResult = ImportsTranslator.jsonToWar(imports);
fs.writeFileSync('war3map.imp', warResult.buffer);

// war3map binary -> JSON
const buffer = fs.readFileSync('war3map.imp');
const { json } = ImportsTranslator.warToJson(buffer);
console.log(json);
// ['war3mapImported\hero_skin.blp', 'war3mapImported\custom_ui.tga', ...]
```
```

--------------------------------

### Translate Sounds JSON to war3map.w3s Binary

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts a JSON array of sound definitions to the binary war3map.w3s format. Utilizes static enums EffectType and Channel for clarity.

```typescript
import { SoundsTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

const { EffectType, Channel } = SoundsTranslator;

// JSON -> war3map binary
const sounds = [
  {
    variableName: 'HumanAmbience',
    internalName: 'HumanAmbience',
    path: 'Sound\Ambient\HumanAmbience.wav',
    effect: EffectType.Default,
    flags: {
      looping: true,
      '3dSound': false,
      stopOutOfRange: false,
      music: false,
      imported: false
    },
    fadeRate: { in: 10, out: 10 },
    volume: 100,
    pitch: 1.0,
    channel: Channel.LoopingAmbient,
    distance: { min: 600, max: 8000, cutoff: 3000 }
  },
  {
    variableName: 'MyImportedSound',
    internalName: 'MyImportedSound',
    path: 'war3mapImported\mysound.mp3',
    flags: { looping: false, '3dSound': true, stopOutOfRange: true, music: false, imported: true },
    fadeRate: { in: 5, out: 5 },
    volume: 127,
    pitch: 1.0,
    channel: Channel.UnitAcknowledgement,
    distance: { min: 400, max: 5000, cutoff: 2000 }
  }
];

const warResult = SoundsTranslator.jsonToWar(sounds);
fs.writeFileSync('war3map.w3s', warResult.buffer);
```

--------------------------------

### Translate Units JSON to war3map Units Binary

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts unit and item placement data from JSON format to the binary war3mapUnits.doo format. Requires importing UnitsTranslator and fs-extra. Enums like PlayerNumber, TargetAcquisition, and ItemClass are available as static properties.

```typescript
import { UnitsTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

const { PlayerNumber, TargetAcquisition, ItemClass } = UnitsTranslator;

// JSON -> war3map binary
const units = [
  {
    type: 'hfoo',
    position: [100.0, 200.0, 0.0],
    rotation: 270,
    player: PlayerNumber.Red,
    id: 1,
    hitpoints: -1,
    mana: -1,
    targetAcquisition: TargetAcquisition.Normal
  },
  {
    type: 'ngol',
    position: [-512.0, 0.0, 0.0],
    rotation: 0,
    player: PlayerNumber.NeutralPassive,
    gold: 25000,
    id: 2
  },
  {
    type: 'Hpal',
    position: [0.0, 0.0, 0.0],
    rotation: 0,
    player: PlayerNumber.Blue,
    hero: { level: 5, str: 10, agi: 5, int: 8 },
    inventory: [{ slot: 1, type: 'rag1' }],
    abilities: [{ ability: 'AHbz', active: false, level: 3 }],
    customItemSets: [{ 'ratf': 50, 'afac': 25 }],
    id: 3
  }
];

const warResult = UnitsTranslator.jsonToWar(units);
fs.writeFileSync('war3mapUnits.doo', warResult.buffer);
```

--------------------------------

### Region Data Structure for JSON

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Regions

Defines the expected structure for region data when converting to the Warcraft 3 region file format. Each region object requires an ID, name, and bounding box coordinates.

```javascript
regionData: [<Region>]; // Array of regions
```

```javascript
{
  id: <Int>,
  name: <String>,
  position: {
    left: <Float>,
    right: <Float>,
    bottom: <Float>,
    top: <Float>
  },
  weatherEffect: <String = '0000'>, // weather effect id
  ambientSound: <String = ''>, // name of sound, defined in .w3s
  color: [<Int = 0>, <Int = 0>, <Int = 0>] // red, green, blue of region used by editor
}
```

--------------------------------

### Convert JSON Camera Data to War3map.w3c

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Cameras

Use the CamerasTranslator.jsonToWar function to convert your camera data. The output buffer can then be written to a war3map.w3c file.

```javascript
import { CamerasTranslator } from 'wc3maptranslator';
var result = CamerasTranslator.jsonToWar(cameraData);
// Now you can write result.buffer to a war3map.w3c file
```

--------------------------------

### Convert JSON to Warcraft 3 WTS Format

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Strings

Use the jsonToWar method to convert a JSON object containing string IDs and values into the Warcraft 3 WTS file format. The output buffer can then be written to a .wts file.

```javascript
import { StringsTranslator } from 'wc3maptranslator';
var result = StringsTranslator.jsonToWar(stringData);
// Now you can write result.buffer to a war3map.wts file
```

--------------------------------

### Translate JSON Doodad Data to War3map.doo Format

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Doodads

Use this snippet to convert an array of doodad objects in JSON format to the binary war3map.doo file format. Ensure you have the DoodadsTranslator imported. The result's buffer property should be written to a .doo file.

```javascript
import { DoodadsTranslator } from 'wc3maptranslator';
var result = DoodadsTranslator.jsonToWar(doodadData);
// Now you can write result.buffer to a war3map.doo file
```

--------------------------------

### Convert JSON to War3map Import Data

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Imports

Use the jsonToWar method to convert an array of import structures into a buffer that can be written to a war3map.imp file. Ensure your importData is correctly formatted.

```javascript
import { ImportsTranslator } from 'wc3maptranslator';
var result = ImportsTranslator.jsonToWar(importData);
// Now you can write result.buffer to a war3map.imp file
```

--------------------------------

### Translate Regions JSON to war3map.w3r Binary

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts a JSON array of region definitions to the binary war3map.w3r format. Ensure the color array is in RGB order, as it's automatically converted to BGR for the binary.

```typescript
import { RegionsTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

// JSON -> war3map binary
const regions = [
  {
    name: 'SpawnZone',
    id: 1,
    position: { left: -512.0, bottom: -512.0, right: 512.0, top: 512.0 },
    weatherEffect: 'RAra',
    ambientSound: 'AmbForest',
    color: [255, 0, 128] 
  },
  {
    name: 'VictoryRegion',
    id: 2,
    position: { left: 1024.0, bottom: 1024.0, right: 2048.0, top: 2048.0 },
    color: [0, 255, 0]
  }
];

const warResult = RegionsTranslator.jsonToWar(regions);
fs.writeFileSync('war3map.w3r', warResult.buffer);
```

--------------------------------

### Translate war3map Terrain Binary to JSON

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts the binary war3map.w3e file back into a JSON representation of the terrain. This includes map dimensions, offset, tileset information, and detailed properties for each tile point.

```typescript
// war3map binary -> JSON
const buffer = fs.readFileSync('war3map.w3e');
const { json } = TerrainTranslator.warToJson(buffer);
console.log(json.tileset);
console.log(json.map.width);
console.log(json.groundHeight[0]);
```

--------------------------------

### SoundsTranslator

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Translates the `war3map.w3s` sound definitions file. It exposes `EffectType` and `Channel` enums as static properties for easier use.

```APIDOC
## SoundsTranslator

Translates the `war3map.w3s` sound definitions file; exposes `EffectType` and `Channel` enums as static properties so numeric channel codes never need to be memorised.

```ts
import { SoundsTranslator } from 'wc3maptranslator';
import * as fs from 'fs-extra';

const { EffectType, Channel } = SoundsTranslator;

// JSON -> war3map binary
const sounds = [
  {
    variableName: 'HumanAmbience',
    internalName: 'HumanAmbience',
    path: 'Sound\Ambient\HumanAmbience.wav',
    effect: EffectType.Default,
    flags: {
      looping: true,
      '3dSound': false,
      stopOutOfRange: false,
      music: false,
      imported: false
    },
    fadeRate: { in: 10, out: 10 },
    volume: 100,
    pitch: 1.0,
    channel: Channel.LoopingAmbient,
    distance: { min: 600, max: 8000, cutoff: 3000 }
  },
  {
    variableName: 'MyImportedSound',
    internalName: 'MyImportedSound',
    path: 'war3mapImported\mysound.mp3',
    flags: { looping: false, '3dSound': true, stopOutOfRange: true, music: false, imported: true },
    fadeRate: { in: 5, out: 5 },
    volume: 127,
    pitch: 1.0,
    channel: Channel.UnitAcknowledgement,
    distance: { min: 400, max: 5000, cutoff: 2000 }
  }
];

const warResult = SoundsTranslator.jsonToWar(sounds);
fs.writeFileSync('war3map.w3s', warResult.buffer);

// war3map binary -> JSON
const buffer = fs.readFileSync('war3map.w3s');
const { json } = SoundsTranslator.warToJson(buffer);
console.log(json[0].variableName);   // 'HumanAmbience'
console.log(json[0].channel);        // 10 (Channel.LoopingAmbient)
```
```

--------------------------------

### Warcraft 3 WTS String Data Specification

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Strings

The stringData object for Warcraft 3 WTS files associates a numeric key (string ID) with its corresponding string value. This format is used for localization in Warcraft 3.

```json
stringData: {
    // Associates a key (id #), with a string value
    "1": "Player 0",
    "2": "Player 1",
    "3": "Player 2",
    "4": "Player 3",
    "5": "Player 4",
    "6": "Player 5",
    ...
}
```

--------------------------------

### Convert JSON to War3map.w3i

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Info

Use InfoTranslator.jsonToWar to convert your map data object into a buffer that can be written to a war3map.w3i file. Ensure you have imported the InfoTranslator class.

```javascript
import { InfoTranslator } from 'wc3maptranslator';
var result = InfoTranslator.jsonToWar(infoData);
// Now you can write result.buffer to a war3map.w3i file
```

--------------------------------

### Translate war3map Doodads Binary to JSON

Source: https://context7.com/chiefofgxbxl/wc3maptranslator/llms.txt

Converts the binary war3map.doo file back into a JSON representation of doodads. The output JSON separates doodads into 'regular' and 'special' arrays, allowing easy access to their properties.

```typescript
// war3map binary -> JSON
const buffer = fs.readFileSync('war3map.doo');
const { json } = DoodadsTranslator.warToJson(buffer);
console.log(json.regular.length);
console.log(json.special.length);
```

--------------------------------

### Convert JSON Unit Data to War Format

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Units

Use the UnitsTranslator.jsonToWar method to convert your unit data from a JSON structure to the binary buffer format required for WAR3 map files. The resulting buffer can then be written directly to a .doo file.

```javascript
import { UnitsTranslator } from 'wc3maptranslator';
var result = UnitsTranslator.jsonToWar(unitData);
// Now you can write result.buffer to a war3mapUnits.doo file
```

--------------------------------

### Output Structure for jsonToWar

Source: https://github.com/chiefofgxbxl/wc3maptranslator/wiki/Home

When converting JSON to WC3 map format, the result includes an 'errors' array and a 'buffer' containing the WC3 data. This buffer can be used with file system modules to create a map file.

```javascript
{
    errors: [],
    buffer: <Buffer 00 00 00...>
}
```