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

npm install wc3maptranslator

Requires Node >= 8
Tested with tsc Version 3.7.2

Usage

JavaScript (version < 3.0.0)

var Translator = require('wc3maptranslator'),
    mapJson = { // Refer to "Specification"
        units: [...],
        doodads: [...],
        ...
    };
var unitResult = new Translator.Units.jsonToWar(mapJson.units);

TypeScript (version >= 3.0.0)

// JS import
const TranslatorLib = require('wc3maptranslator');
const Translator = new TranslatorLib();
console.log(Translator);

//... or TS import
import { Translator } from 'wc3maptranslator';
const myTranslator = new Translator();
console.log(Translator);

Using the Translator

// 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 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 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 for the detailed documentation of the files found in a .w3x archive. Two tutorials are here (1) and here (2).