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

Table of Contents

• Overview
• Support
  • Support Files
  • Object data files
  • Trigger files
  • Map files
  • Raw and binary pass-through files
• Getting Started
  • Prerequisites
  • Import
  • Development
• 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.

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:

1. Clone the repo

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

2. Enter the correct directory

cd war3map

3. Install NPM packages

npm install

4. Run All Tests

npm test

For local Warcraft III sample validation, build the project and compare every parsed archive subfile with its dumped bytes:

npm run test:local-maps

Set WAR3_MAPS_DIR to scan a different map directory.

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.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. 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.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Invoker Bot - [email protected]

Project Link: https://github.com/invoker-bot/war3map

Acknowledgements

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