@voces/wc3maptranslator

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

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).