Skip to content

Latest commit

 

History

History
164 lines (131 loc) · 12.5 KB

README.md

File metadata and controls

164 lines (131 loc) · 12.5 KB
Raw

WC3MapTranslator

Translate war3map ⇄ json formats for WarCraft III .w3x maps

Quality

Known Vulnerabilities

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.

This API is a core component of Ice Sickle, the next-generation world editor. Ice Sickle stores data in a JSON format, and then generates all the necessary files to assemble a .w3x MPQ archive to build a map.

Install

npm install wc3maptranslator

Usage

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

// Using individual translators, we may convert JSON
// representation to generate a WC3 .w3x map file.
// See the Wiki for more information.

var unitResult = new Translator.Units.jsonToWar(mapJson.units);
// We can now write the `unitResult.buffer` content to a file named "war3mapUnits.doo" and put it in a .w3x archive!

Examples

There is an /examples directory that demonstrates how to use each translator. This is a great starting point to learn how to use any translator. The directory has jsonToWar, and warToJson, sample projects to convert from JSON to war3map files and back.

To get started with either example, cd into /examples/[whichever] and run npm install to automatically install all the dependencies. Run npm start under /examples/[whichever] to display a list of each command to run.

image

For example, to run the "Cameras" translator, your working directory should be /examples/jsonToWar, and then you'll run the command node entity/cameras.js. Take a look at the source code under jsonToWar/entity, jsonToWar/object, or jsonToWar/other to see how to use each translator.

All output files are placed in the output directory.

File Support

World files

Type Json → War War → Json File
Terrain check times war3map.w3e
Units check check war3mapUnits.doo
Doodads check check war3map.doo
Regions check check war3map.w3r
Cameras check check war3map.w3c
Sounds (definitions) check check war3map.w3s

Object data files

Type Json → War War → Json File
Units - Objects check check war3map.w3u
Items - Objects check check war3map.w3t
Abilities - Objects check check war3map.w3a
Destructables - Objects check check war3map.w3b
Doodads - Objects check check war3map.w3d
Upgrades - Objects check check war3map.w3q
Buffs - Objects check check war3map.w3h

Trigger files

Type Json → War War → Json File
JASS times times war3map.j
Strings check check war3map.wts

Map files

Type Json → War War → Json File
Info File check check war3map.w3i
Imported Files check check war3map.imp
Pathing times times war3map.wpm
Shadow map times times war3map.shd

Not included

times Custom Text Trigger File (war3map.wct)
times Trigger Names File (war3map.wtg)
times Menu Minimap (war3map.mmp)
times Minimap Image (war3mapMap.blp)
times Minimap Image (war3mapMap.b00
times Minimap Image (war3mapMap.tga)
times 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).