W3M and W3X Files Format

Last update: 9/03/2006
Introduction

This documentation contains almost all the
specifications of Warcraft III maps files (*.w3m and *.w3x). This was made without any help from Blizzard Entertainement and did not involve "reverse engineering" of the Warcraft III engine. The specification of each kind of file depend on its version. I did document here the current version used by Warcraft III Retail (initial version); make sure the file you're looking at or modifying are using the same version/format as describbed. I'm French so please, forgive my English! Finally, use this documentation at your own risks: I take no responsability if you corrupt your maps.

**++1) Things
you need to know first to mod' a map!++**

1.1) Your environment

You'll need Warcraft III Retail installed let's say in
"C:\Program Files\Warcraft III\".
I'll talk about files of Warcraft 3 Retail (initial version) here,
that's why some files format can vary depending which version you're
using; you may have to figure out some differences in the file formats.
I'll also describe the new format of in the expansion The Frozen
Throne, if the file format got changed. If your Warcraft III
installation is clean, you should have these files (of course, there
are other files in there but I'll uses these for exemples):
in your "C:\Program Files\Warcraft III\":
   - war3.mpq
and in your "C:\Program Files\Warcraft III\Maps\":
   - (4)Lost Temple.w3m
   (and many other w3m of course...)
If you have also installed the expansion The Frozen Throne, you'll have other archives that hold the new files. These are:
   __ - war3x.mpq
   - war3xlocal.mpq
and in your "C:\Program Files\Warcraft III\Maps\FrozenThrone\__":
   __ -(2)Circumvention.w3x
   __ (as an example)
and in your "C:\Program Files\Warcraft III\Campaigns\":
   -DemoCampaign.w3n
Also by installing updates a new archive will be added that holds the most up-to-date files from the patch, namely
   -war3patch.mpq



"W3M" and "W3X" and also map files as well as "W3N" campaign files can be opened with any MPQ editor that supports Warcraft 3.

You'll need one. I suggest WinMPQ (ShadowFlare), you can get it here:

   shadowflare.samods.org/dwnload.html

   Read the documentation and installation notes.
You can also use Ladik's MPQ Editor which you can get here:
   www.zezula.net/en/mpq/download.html
   Place it in a folder and run it.
Another option would be PowerMPQ which is also available in Italian and German:
www.wc3campaigns.net/showthread.php?t=58908

   This one also allows creating executable patches which requires MPQDraft in the same directory.

If you only see unknown files when opening maps or other archives you will also need up-to-date listfiles.
You can get the latest listfiles for Warcraft at www.wc3campaigns.net/tools/weu/stuff.html
All the above mentioned editors have a settings dialog where you can
specify external listfiles that will be looked up for fmissing
filenames. Simply add all your listfiles to this list and most unknown
files should be identified now.

If you want to "play" with the map files, you'll also need a hexadecimal editor.
My favorite one is HexWorkshop (www.bpsoft.com).
A freeware alternative is XVI32 found at www.chmaas.handshake.de but it lacks quite a bunch of useful features.


1.2) Warcraft 3 Files

1.2.1) About  MPQ Files

MPQ are like "zip" or "rar" files as they contain a
directory structure with compressed files.
I'll not talk about the MPQ format here since Quantam did it already. If you want to know more about it I
suggest you go there:
www.zezula.netIf you want to edit MPQ archives I suggest you get SFmpqapi for your favourite programming language. It's available at
shadowflare.samods.org/dwnload.html for
several programming languages including Delphi, C++ and Visual Basic.
You can also download the source code of WinMPQ there to learn how to
use SFmpqapi.

1.2.2) Warcraft III File Structure

When it's looking for a file, Warcraft III looks first in the "real"
directories (the one you see in Windows Explorer) ++if you set up a specific
registery key++ which is:
   Path: HKEY_CURRENT_USER\Software\Blizzard Entertainment\Warcraft III\
   Key name: "Allow Local Files"
   Key type: dword
   Key value: 1

If the registery key is not set or the file was not found in the "real"
directories, then it looks in your map (w3m file), then in the last
patch mpq (War3Patch.mpq) and finally in the main mpq (War3x.mpq or
War3xlocal.mpq if the expansion is installed) and lately in War3.mpq.
It means that you don't need to modify official MPQs (DON'T modify your War3.mpq!), you just need to
use the same directory/file structure in your "C:\Program Files\Warcraft III\".
Adding files in a map (.w3m
file) works with most of the files but not all. Remember that the
WorldEditor reads the local files from the real directories even if
"Allow Local Files" is not enabled in the registry.
It Works (for example) for:
__   Units\unitUI.slk   Units\AbilityData.slk
   UI\MIDISounds.slk
   Units\HumanUnitFunc.txt
   Units\HumanUnitStrings.txt
   Units\HumanAbilityFunc.txt
   Units\HumanAbilityStrings.txt
   Units\HumanUpgradeFunc.txt
   Units\HumanUpgradeStrings.txt
__
But it doesn't work very well for:
__   Units\UnitMetaData.slk
   Scripts\Blizzard.j
__
And it doesn't work at all for:
__   TerrainArt\CliffTypes.slk
____   Units\MiscData.txt
__
If you really need to change a file that has to be loaded outside or
before a map is loaded, I recommend you create a executable patch with
a embedded MPQ archive using MPQDraft, which you can download at the
above-mentioned link. This option is also used by the third party
editors such as UMSWE.

++
Example:
++You
want to use more than the two default cliff types in a map. By editing
the w3e file or by using WE Unlimited or Zepir's Editor you can
technically add more cliff types to your map. The problem is that to
have them show up correctly in game it will require a modified
TerrainArt\CliffTypes.slk file. To make this work you will have to
create a new MPQ Archive and import the modified file with the path
TerrainArt\CliffTypes.slk. Also take care that a listfile entry is
added for this file. Then start MPQDraft and create a new executable
patch. Simply select the created archive as source and select Warcraft
III as the target application to patch. That's it, the patch will be
created for you. Now if you start the created executable it will start
Warcraft and the modified file will be used instead of the original one.

**
Warning!

   **- In some cases, if you play with others, everybody will need to have the same
modified files or you'll get an error (like "netsync error").

   - Some files have a "special" format and if you modify them, you could
"falsify" this format. In some cases it will work, in some others it won't. Be aware of that 'cause
War3 will try to find a "standard file" instead (the ones of the MPQs instead of yours and
you'll think it didn't try your stuff).

   - Some files outside both War3.mpq and War3Patch.mpq will not be used by Warcraft

3. These are exceptions.
    

1.2.3) Map files (W3M/W3X Files)

To edit a map, you'll have to unpack the files of the "w3m" somewhere,
then modify them and finally put them back in a "w3m" file (usually a new one).
Since retail, W3M are a little bit different from simple MPQ files: they got a
header and a footer. I'll talk more about the W3M format in the "W3M Files Format" section and
the other files inside W3Ms in the following sections.

1.3) Warcraft 3 Data Format

Blizzard uses several ways to store data in its files. However they often use generic types.
-Integers

Intergers are stored using 4 bytes in "Little Endian" order. It means
that the first byte read is the lowest byte.
They are just like the C++ "int" (signed) type. In some other
documentation of this kind you may see them named "long".
Size: 4 bytes
Example: 1234 decimal = [00 00 04 D2]h will be stored in this order: [D2 04 00
00]h

-Short Integers

Short Integers are stored using 2 bytes in "Little Endian" order.
They are close to the C++ signed short but their range is from -16384 to 16383.
It means the 2 highest bit are free of use for a flag for example.Size: 2 bytes

-Floats

Floats are using the standard IEEE 32bit float format. They are stored using 4
bytes and the "Little Endian" order.
They are just like the C++ "float" type.
Size: 4 bytes
Example: 7654.32 decimal, this number can't be stored using this format so the
system will take the closest value that can be represented using binary digits. The closest one is:
7654.319824 decimal = [45 EF 32 8F]h and will be stored as [8F 32 EF 45]h

-Chars and Array of Chars

They are just stored like standard chars (1 char = 1 byte) and array of chars
(no null terminating char needed).
Size (chars): 1 byte
Size (array of chars): usually 4 bytes

-Trigger Strings and Strings

Strings are just arrays of chars terminated with a null char (C++ '\0'). However
Blizzard sometimes use special control codes to change the displayed color for the string. These codes are like
"|c00BBGGRR" where "BB", "GG" and
"RR" are hexadecimal values (using 2 digits each) for the blue, the
green and the red values. If a string starts with "TRIGSTR_" (case sensitive), it's considered
as a trigger string. A trigger string is kept in memory as is ("TRIGSTR_***") and is only
changed when Warcraft 3 needs to display it. Instead of just writing "TRIGSTR_000" on the user screen, War3 will
look in its trigger string table created when the map was loaded and display the corresponding trigger string instead. Trigger
strings only work for files inside a w3m (Jass, w3i, ...) except for the WTS which is used to define the trigger
string table itself. If the number following "TRIGSTR_" is negative the trigger string will refer to a
null (empty) string, if "TRIGSTR_" is followed by text, it'll be considered as trigger string #0 ( = "TRIGSTR_000").
"TRIGSTR_7", "TRIGSTR_07", "TRIGSTR_007" and
"TRIGSTR_7abc" are all representing trigger string #7. "TRIGSTR_ab7", "TRIGSTR_abc" and "TRIGSTR_" refer
to trigger string #0. "TRIGSTR_-7" is negative and will not refer to a trigger string; it'll
be displayed as"". By convention, "TRIGSTR_" is followed by 3 digits and the null char
that ends the string.
Example 1: your got the string "blah |c000080FFblah", War3 will display
"blah blah" but the second "blah" will be orange (blue=00 + green=80 + red=FF ==> orange)
Example 2: you got "TRIGSTR_025" and trigger string 25 is defined (in
the .wts file) as "blah|c000080FFblah", it'll display the same result as the previous example.
Size (string): vary. String length + 1 (null terminating char)Size (trigger string): 12 bytes
 
For
its strings Warcraft uses a unicode format called UTF-8. They do this
because the files need to be localized into many different languages.
This format uses one byte for the most common characters which is equal
to the character's ASCII value. For example A = 65 or 0x41. For the
more unusual characters it can take from 2 to 6 bytes per character.
For example the German letter Д would be represented by 195 and 164 or
0xC3A4. The higher the first byte is, the more bytes are required to
represent the character. Simple modulo calculations are enough to
convert UTF to common unicode (UCS) and back. To convert UTF to UCS use
this pattern:
 
 
If FirstByte <= 191 return FirstByte
 If 192 <= FirstByte <= 223 return (FirstByte - 192) * 64 + (SecondByte - 128)
 If 224 <= FirstByte <= 239 return (FirstByte - 224) * 4096 + (SecondByte - 128) * 64 + (ThirdByte - 128)
If 240 <= FirstByte <= 247 return (FirstByte - 240) * 262144 +
(SecondByte - 128) * 4096 + (ThirdByte - 128) * 64 + (FourthByte - 128)
If 248 <= FirstByte <= 251 return (FirstByte - 248) * 16777216 +
(SecondByte - 128) * 262144 + (ThridByte - 128) * 4096 + (FourthByte -
128) * 64 + (FifthByte - 128)
If 252 <= FirstByte return (FirstByte - 252) * 1073741824 +
(SecondByte - 128) * 16777216 + (ThirdByte - 128) * 262144 +
(FourthByte - 128) * 4096 + (FifthByte - 128) * 64 + (SixthByte - 128)
 
To convert UCS back to UTF use this:
 
If ASCII <= 127 FirstByte = ASCII
 If 128 <= ASCII <= 2047 FirstByte = 192 + (ASCII \ 64) SecondByte = 128 + (ASCII Mod 64)
If 2048 <= ASCII <= 65535 FirstByte = 224 + (ASCII \ 4096)
SecondByte = 128 + ((ASCII \ 64) Mod 64) ThirdByte = 128 + (ASCII Mod
64)
If 65536 <= ASCII <= 2097151 FirstByte = 240 + (ASCII \ 262144)
SecondByte = 128 + ((ASCII \ 4096) Mod 64) ThirdByte = 128 + ((ASCII \
64) Mod 64) FourthByte = 128 + (ASCII Mod 64)
If 2097152 <= ASCII <= 67108863 FirstByte = 248 + (ASCII \
16777216) SecondByte = 128 + ((ASCII \ 262144) Mod 64) ThirdByte = 128
+ ((ASCII \ 4096) Mod 64) FourthByte = 128 + ((ASCII \ 64) Mod 64)
FifthByte = 128 + (ASCII Mod 64)
If 67108864 <= ASCII <= 2147483647 FirstByte = 252 + (ASCII \
1073741824) SecondByte = 128 + ((ASCII \ 16777216) Mod 64) ThirdByte =
128 + ((ASCII \ 262144) Mod 64) FourthByte = 128 + ((ASCII \ 4096) Mod
64) FifthByte = 128 + ((ASCII \ 64) Mod 64) SixthByte = 128 + (ASCII
Mod 64))
 
The
conversion will only be needed if you want to display text in your
application or write user input to files. For all other purposes you
can internally treat the UTF-Strings just like ordinary strings.
 

-Flags

Flags are boolean values (true or false, 1 or 0). They can be stored using 4
bytes. Each bit is a flag (4 bytes = 32 bit = 32 flags). Blizzard uses integers to store its flags.
Size: usually 4 bytes

-Custom Types

Sometimes, an integer and one or several flags can share bytes. This is the case
in the W3E file
format: the water level and 2 flags are using the same group of 4 bytes. How?
the 2 highest bit are used for the flags, the rest is reserved for the water level (the value range is
just smaller). Sometimes a byte can contain two or more different data.

-Structures:

Warcraft 3 also uses structured types of various size.

**
2) W3M/W3X Files Format**

A W3M or W3X file is a
Warcraft III Map file (AKA Warcraft III Scenario in the World Editor).
It's just a MPQ (using a "new" compression format) with a 512 bytes
header. Sometimes, for official W3M files, it uses a footer of 260
bytes for authentification purposes.

Here is the header format (fixed size = 512 bytes):
char[4]: file ID (should be "HM3W")
int: unknown
string: map name
int: map flags (these are exactly the same as the ones in the W3I file)
0x0001: 1=hide minimap in preview screens
0x0002: 1=modify ally priorities
0x0004: 1=melee map
0x0008: 1=playable map size was large and has never been reduced to medium
0x0010: 1=masked area are partially visible
0x0020: 1=fixed player setting for custom forces
0x0040: 1=use custom forces
0x0080: 1=use custom techtree
0x0100: 1=use custom abilities
0x0200: 1=use custom upgrades
0x0400: 1=map properties menu opened at least once since map creation
0x0800: 1=show water waves on cliff shores
0x1000: 1=show water waves on rolling shores
int: max number of players
followed by 00 bytes until the 512 bytes of the header are filled.
Here is the footer format (optional):
char[4]: footer sign ID (should be "NGIS" == 'sign' reversed)
byte[256]: 256 data bytes for authentification. I don't know how they are used
at the moment.

The MPQ part can contain the following files:
(listfile)
(signature)
(attributes)
war3map.w3e
war3map.w3i
war3map.wtg
war3map.wct
war3map.wts
war3map.j
war3map.shd
war3mapMap.blp
war3mapMap.b00
war3mapMap.tga
war3mapPreview.tga
war3map.mmp
war3mapPath.tga
war3map.wpm
war3map.doo
war3mapUnits.doo
war3map.w3r
war3map.w3c
war3map.w3s

war3map.w3u
war3map.w3t
war3map.w3a
war3map.w3b
war3map.w3d
war3map.w3q
war3mapMisc.txt
war3mapSkin.txt
war3mapExtra.txt
war3map.imp
war3mapImported\*.* 

We'll see now what these files stand for.
 

**
++

3. "war3map.j" The JASS2

Script++**

This is the main map script file. It's a text file and you can open it with
notepad.
Sometimes it's renamed to Scripts\war3map.j by map protectors to keep you away from it.The language used is called JASS2 and has been developed by Blizzard. It's a case sensitive language.
When you play a map, the jass script is loaded and executed.
When you select a map in when creating a game Warcraft III will first
look up the "config" function and execute its code to set up the player
slots.Then, when the game has started, Warcraft III looks for the function called "main" and executes it.