war3map

Not finished yet, please wait until version >= 1.0.0.

WAR3MAP

An awesome war3 map translator library for your project!
Explore the docs »

View Repository · Report Bug · Request Feature

Overview
Support
Getting Started
Roadmap
Contributing
License
Contact
Acknowledgements

Overview

War3map is a module to convert between a Object representation of WarCraft III (.w3x) data and war3map format files.

TranslationExample

War3map is written in TypeScript, offering type safety and improved development experience.

Here's some places where you can use this library:

You need to decompile a map of Warcraft 3.
You want to write a map editor for Warcraft 3.
You want to optimize or encrypt your Warcraft 3 map.

Support

Support Files

Type	Object → War	War → Object	File
Environment			war3map.w3e
Units			war3mapUnits.doo
Doodads			war3map.doo
Regions			war3map.w3r
Cameras			war3map.w3c
Sounds(definitions)			war3map.w3s

UnitsObject supports both RoC war3mapUnits.doo v7/subversion 9 and TFT v8/subversion 11 layouts, including byte-preserving duplicate item drops. EnvironmentObject supports terrain war3map.w3e v11 and Reforged v12 texture flag layouts.

Object data files

Type	Object → War	War → Object	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	Object → War	War → Object	File
LUA			war3map.lua
JASS			war3map.j
Strings			war3map.wts
Custom Text Triggers			war3map.wct
Trigger Definitions			war3map.wtg

TriggerNamesObject preserves full war3map.wtg bytes and exposes Reforged root metadata, type counts, variable definitions, and tree-object summaries. Pass triggerData from UI\TriggerData.txt to parse GUI functions and parameter lists; without it, the raw payload is still preserved.

Map files

Type	Object → War	War → Object	File
Info File			war3map.w3i
Imported Files			war3map.imp
Pathing			war3map.wpm
Shadow map			war3map.shd
Menu Minimap			war3map.mmp
Game Configuration			*.wgc

SoundsObject exposes pitch and distance values as numeric fields and keeps the World Editor metadata/tail markers structured for byte-for-byte round trips. GameConfigurationObject supports the .wgc files generated by World Editor AI test runs.

Image and payload-preserving files

These files expose validated headers or editable text while preserving payload bytes for byte-for-byte archive rebuilds.

BLP1/BLP2 minimap and imported images (war3mapMap.blp, *.blp)
TGA and DDS preview, pathing, and imported images (*.tga, *.dds)
Image conversion helpers for PNG, TGA, DDS, BLP1 JPEG/paletted images, and BLP2 BGRA/DXT images
MDX model chunks, materials, geosets, animation tracks, geoset animations, texture animations, global sequences, pivots, bones, helpers, attachments, cameras, events, collision shapes, ribbon emitters, and particle emitters 2 (*.mdx)
WAV/MP3 audio headers, including empty WAV override placeholders (*.wav, *.mp3)
WAI AI editor headers plus condition/function/string summaries (*.wai)
Text resource pass-through for SLK/FDF/TOC/INI/TXT/AI files
Opaque fallback payloads through RawFileObject

MDX files also expose knownChunkErrors when a known chunk is preserved but cannot be safely decoded into the structured view. Treat these diagnostics as a conversion warning and keep the original chunk bytes unless the format variant is understood.

Getting Started

Prerequisites

NODEJS
*VERSION >= 10**

Installation

The easiest and fastest way is to use it as a library. Just simply type the followings:

npm
```
npm install war3map
```

Import

Create your .ts or .js file, and type as follows:

import * as war3map from "war3map";

To get more examples or usages for war3map, see Documentation.

Archive Support

MapArchiveObject can read and write .w3m, .w3x, and .mpq archives through node-stormlib. node-stormlib only handles the MPQ container; this package parses the map files inside the archive. Install node-stormlib or set NODE_STORMLIB_PATH to a local checkout such as D:\Projects\GitHub\node-storm.

import { MapArchiveObject } from "war3map";

const map = new MapArchiveObject();
map.readArchive("example.w3x");
map.writeArchive("out/example.w3x", { overwrite: true });

Development

To get a local copy up and running follow these simple steps:

Clone the repo

git clone https://github.com/invoker-bot/war3map.git

Enter the correct directory
```
cd war3map
```
Install NPM packages
```
npm install
```
Run All Tests
```
npm test
```

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

Your code should:

Run correctly (Run npm test without errors.)
Include tests (Write unit tests and run npm run test:coverage to cover most of your code.)
Be linted (Run npm run lint and follow the project's coding standards.)
Pass CI (GitHub Actions must pass on supported Node.js versions.)

If your code is accepted into master, we will invite you to be a project member as soon.

This project refers a lot from WC3MapTranslator written by ChiefOfGxBxL. Our goal is same but offers different API, and plan more features.
We owe a lot of thanks to Chocobo on TheHelper for the detailed documentation of the files found in a .w3x archive. And another two tutorials are here (1) and here (2) and here (3).