WC3MapTranslator
Translate war3map ⇄ json formats for WarCraft III .w3x maps
Quality
Info
Overview ·
Install ·
Usage ·
Examples ·
File Support ·
Specification ·
Contributing ·
Special Thanks
## Overview
WC3MapTranslator is a module to convert a JSON representation of WarCraft III (.w3x) data to their `war3map` files, and vice-versa. This makes the map data readable and easily modifiable.
WC3MapTranslator is written in `TypeScript` starting from version `3.0.0`, offering type safety and improved development experience.
## Install
```ts
npm install wc3maptranslator
```
**Requires Node >= 8**
**Tested with tsc Version 3.7.2**
## Usage
### JavaScript (version < 3.0.0)
```ts
var Translator = require('wc3maptranslator'),
mapJson = { // Refer to "Specification"
units: [...],
doodads: [...],
...
};
var unitResult = new Translator.Units.jsonToWar(mapJson.units);
```
### TypeScript (version >= 3.0.0)
```js
// JS import
const TranslatorLib = require('wc3maptranslator');
const Translator = new TranslatorLib();
console.log(Translator);
```
```ts
//... or TS import
import { Translator } from 'wc3maptranslator';
const myTranslator = new Translator();
console.log(Translator);
```
### Using the Translator
```ts
// e.g. unit translator
const unitResult = new Translator.Units.jsonToWar(mapJson.units);
// all:
* Doodads
* Strings
* Terrain
* Units
* Regions
* Cameras
* Sounds
* Objects
* Imports
* Info
```
We can now write the `unitResult.buffer` content to a file named "war3mapUnits.doo" and put it in a .w3x archive! Using individual translators, we may convert JSON representation to generate a WC3 .w3x map file. See the Wiki for more information.
## Examples
There is an `examples` directory that demonstrates how to use *each* translator, both for converting from war3map to JSON, and JSON to war3map formats. This is a great starting point to learn how to use any translator.
To get started with either example, `cd` into `/examples/` and run `npm install` to install all the dependencies. Then run `npm start` which kicks off the TypeScript build and then executes the resulting JavaScript. A few output files will be written under the `/examples/` directory, but the output is purposely not comprehensive to avoid spamming the directory and because the translation process is sufficiently demonstrated using just one example of translating in each direction.
## 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 included
 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
We have a detailed [specification on our Wiki](https://github.com/ChiefOfGxBxL/WC3MapTranslator/wiki) 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.
The underlying WarCraft map files (e.g. war3map.doo) have been documented [on our Wiki](https://github.com/ChiefOfGxBxL/WC3MapTranslator/wiki) as well. If you are curious about how a .w3x file is composed, this is the place to learn!
## 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 `master`
**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 `master`. 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).