# WC3MapTranslator
**Repository Path**: cecilz/WC3MapTranslator
## Basic Information
- **Project Name**: WC3MapTranslator
- **Description**: Translate war3map ⇄ json formats for WarCraft III .w3x maps
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-29
- **Last Updated**: 2025-04-04
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
WC3MapTranslator
Translate war3map ⇄ json formats for WarCraft III .w3x maps
Quality
Overview ·
Install ·
Usage ·
File Support ·
Specification ·
Contributing ·
Special Thanks
## Overview
WC3MapTranslator is a TypeScript module to convert between JSON and WarCraft III (.w3x) `war3map` formats. This makes the map data readable and easily modifiable, a perfect format for storing WC3 maps in Git repositories and inspecting diffs!
## Install
```ts
npm install wc3maptranslator
```
**Requires Node ≥ 14**
## 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);
```
## File Support
### World files
| Type | Json → War | War → Json | File |
|-------------------------|:-----------:|:-----------:|---------------|
| Terrain |  |  | war3map.w3e |
| Units |  |  | war3mapUnits.doo |
| Doodads |  |  | war3map.doo |
| Regions |  |  | war3map.w3r |
| Cameras |  |  | war3map.w3c |
| Sounds (definitions) |  |  | war3map.w3s |
### Object data files
| Type | Json → War | War → Json | File |
|-------------------------|:-----------:|:-----------:|---------------|
| Units - Objects |  |  | war3map.w3u |
| Items - Objects |  |  | war3map.w3t |
| Abilities - Objects |  |  | war3map.w3a |
| Destructables - Objects |  |  | war3map.w3b |
| Doodads - Objects |  |  | war3map.w3d |
| Upgrades - Objects |  |  | war3map.w3q |
| Buffs - Objects |  |  | war3map.w3h |
### Trigger files
| Type | Json → War | War → Json | File |
|-------------------------|:-----------:|:-----------:|---------------|
| LUA |  |  | war3map.lua |
| JASS |  |  | war3map.j |
| Strings |  |  | war3map.wts |
### Map files
| Type | Json → War | War → Json | File |
|-------------------------|:-----------:|:-----------:|---------------|
| Info File |  |  | war3map.w3i |
| Imported Files |  |  | war3map.imp |
| Pathing |  |  | war3map.wpm |
| Shadow map |  |  | war3map.shd |
### Not relevant
 Custom Text Trigger File (war3map.wct)
 Trigger Names File (war3map.wtg)
 Menu Minimap (war3map.mmp)
 Minimap Image (war3mapMap.blp)
 Minimap Image (war3mapMap.b00
 Minimap Image (war3mapMap.tga)
 Map Preview Image (war3mapPreview.tga)
## Specification
### WC3MapTranslator format
We have a detailed explaining how to format a map in JSON. It explains everything from the high-level map object, all the way down to creating individual units, tiles, or custom objects.
> 🔗 [WC3MapTranslator format](https://github.com/ChiefOfGxBxL/WC3MapTranslator/wiki)
### war3map format
The underlying WarCraft map files (e.g. war3map.doo) have been documented in a separate repository. If you are curious about how a .w3x file is composed, this is the place to learn!
> 🔗 [WC3MapSpecification](https://github.com/ChiefOfGxBxL/WC3MapSpecification)
## Contributing
We encourage contributions! Generally, the process of making a change is:
1. Fork this repo
2. Develop your changes on a new branch
3. Submit a pull request to `dev`
**Your code should**:
* **run** (your code needs to work, of course)
* **include tests** (write unit tests to demonstrate your code works under different conditions)
* **be linted** (run `npm run lint` and follow the project's coding standards)
* **pass CI** (we enforce: ESLint, unit tests pass, code coverage)
A code review is required on your PR to be accepted into `dev`. A project member will get back to you within one week. If you haven't heard from someone regarding your PR, feel free to ping @chiefofgxbxl.
## Special Thanks
We owe a lot of thanks to *Chocobo* on [TheHelper](http://www.thehelper.net/) for the detailed documentation of the files found in a .w3x archive. Two tutorials are [here (1)](http://www.thehelper.net/threads/guide-explanation-of-w3m-and-w3x-files.35292/) and [here (2)](http://world-editor-tutorials.thehelper.net/cat_usersubmit.php?view=42787).